-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Minimalistic actor library experiments
--   
--   Design space exploration for the "theatre" library. Don't expect this
--   lib to maintain a stable API. Once clearly useful abstractions emerge,
--   they'll be moved to the "theatre" lib.
@package theatre-dev
@version 0.2

module TheatreDev

-- | Controls of an actor, which processes the messages of type
--   <tt>message</tt>. The processing runs on a dedicated green thread.
--   
--   Provides abstraction over the message channel, thread-forking and
--   killing.
--   
--   Monoid instance is not provided for the same reason it is not provided
--   for numbers. This type supports both sum and product composition. See
--   <a>allOf</a> and <a>oneOf</a>.
data Actor message

-- | Spawn an actor which processes messages in isolated executions and
--   threads state.
spawnStatefulIndividual :: state -> (state -> IO ()) -> (state -> message -> IO state) -> IO (Actor message)

-- | Spawn an actor which processes all available messages in one execution
--   and threads state.
spawnStatefulBatched :: state -> (state -> IO ()) -> (state -> NonEmpty message -> IO state) -> IO (Actor message)

-- | Spawn an actor which processes messages in isolated executions.
spawnStatelessIndividual :: IO () -> (message -> IO ()) -> IO (Actor message)

-- | Spawn an actor which processes all available messages in one
--   execution.
spawnStatelessBatched :: IO () -> (NonEmpty message -> IO ()) -> IO (Actor message)

-- | Add a message to the end of the queue of the messages to be processed
--   by the provided actor.
tell :: Actor message -> message -> IO ()

-- | Command the actor to stop registering new messages, process all the
--   registered ones and execute the clean up action.
--   
--   This action executes immediately. If you want to block waiting for the
--   actor to actually die, after <a>kill</a> you can run <a>wait</a>.
kill :: Actor message -> IO ()

-- | Block waiting for the actor to die either due to getting killed or due
--   to its interpreter action throwing an exception. The exception will
--   get rethrown here.
wait :: Actor message -> IO ()

-- | Distribute the message stream across actors. The message gets
--   delivered to the first available one.
--   
--   E.g., using this combinator in combination with <a>replicateM</a> you
--   can construct pools:
--   
--   <pre>
--   spawnPool :: Int -&gt; IO (Actor message) -&gt; IO (Actor message)
--   spawnPool size spawn =
--     oneOf &lt;$&gt; replicateM size spawn
--   </pre>
--   
--   You can consider this being an interface to the Sum monoid.
oneOf :: [Actor message] -> Actor message

-- | Distribute the message stream to all provided actors.
--   
--   You can consider this being an interface to the Product monoid.
allOf :: [Actor message] -> Actor message

-- | Dispatch the message across actors based on a key hash.
--   
--   This lets you ensure of a property that messages with the same key
--   will arrive to the same actor, letting you maintain a local associated
--   state in the actors.
--   
--   The implementation applies a modulo equal to the amount of actors to
--   the hash and thus determines the index of the actor to dispatch the
--   message to. This is inspired by how partitioning is done in Kafka.
byKeyHash :: (message -> Int) -> [Actor message] -> Actor message
instance Data.Functor.Contravariant.Contravariant TheatreDev.Actor
instance Data.Functor.Contravariant.Divisible.Divisible TheatreDev.Actor
instance Data.Functor.Contravariant.Divisible.Decidable TheatreDev.Actor