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


-- | Message passing concurrency as extensible-effect
--   
--   Please see the README on GitHub at
--   <a>https://github.com/sheyll/extensible-effects-concurrent#readme</a>
@package extensible-effects-concurrent
@version 0.2.0.3


-- | The message passing effect.
--   
--   This module describes an abstract message passing effect, and a
--   process effect, mimicking Erlang's process and message semantics.
--   
--   An implementation of a handler for these effects can be found in
--   <a>ForkIOScheduler</a>.
module Control.Eff.Concurrent.Process

-- | Each process is identified by a single process id, that stays constant
--   throughout the life cycle of a process. Also, message sending relies
--   on these values to address messages to processes.
newtype ProcessId
ProcessId :: Int -> ProcessId
[_fromProcessId] :: ProcessId -> Int
fromProcessId :: Iso' ProcessId Int

-- | The process effect is the basis for message passing concurrency. This
--   effect describes an interface for concurrent, communicating isolated
--   processes identified uniquely by a process-id.
--   
--   Processes can raise exceptions that can be caught, exit gracefully or
--   with an error, or be killed by other processes, with the option of
--   ignoring the shutdown request.
--   
--   Process Scheduling is implemented in different modules. All scheduler
--   implementations should follow some basic rules:
--   
--   <ul>
--   <li>fair scheduling</li>
--   <li>sending a message does not block</li>
--   <li>receiving a message does block</li>
--   <li>spawning a child blocks only a very moment</li>
--   <li>a newly spawned process shall be scheduled before the parent
--   process after</li>
--   <li>the spawn</li>
--   <li>when the first process exists, all process should be killed
--   immediately</li>
--   </ul>
data Process (r :: [Type -> Type]) b

-- | Return the current <a>ProcessId</a>
[SelfPid] :: Process r (ResumeProcess ProcessId)

-- | Start a new process, the new process will execute an effect, the
--   function will return immediately with a <a>ProcessId</a>.
[Spawn] :: Eff (Process r : r) () -> Process r (ResumeProcess ProcessId)

-- | Process exit, this is the same as if the function that was applied to
--   a spawn function returned.
[Shutdown] :: Process r a

-- | Exit the process due to an error, this cannot be caught.
[ExitWithError] :: String -> Process r b

-- | Raise an error, that can be handled.
[RaiseError] :: String -> Process r b

-- | Request that another a process exits. The targeted process is
--   interrupted and gets a <a>ShutdownRequested</a>, the target process
--   may decide to ignore the shutdown requests.
[SendShutdown] :: ProcessId -> Process r (ResumeProcess Bool)

-- | Send a message to a process addressed by the <a>ProcessId</a>. Sending
--   a message should **always succeed** and return **immediately**, even
--   if the destination process does not exist, or does not accept messages
--   of the given type.
[SendMessage] :: ProcessId -> Dynamic -> Process r (ResumeProcess Bool)

-- | Receive a message. This should block until an a message was received.
--   The pure function may convert the incoming message into something, and
--   the result is returned as <tt>ProcessMessage</tt> value. Another
--   reason why this function returns, is if a process control message was
--   sent to the process. This can only occur from inside the runtime
--   system, aka the effect handler implementation. (Currently there is one
--   in <a>ForkIOScheduler</a>.)
[ReceiveMessage] :: Process r (ResumeProcess Dynamic)

-- | <i>Cons</i> <a>Process</a> onto a list of effects.
type ConsProcess r = Process r : r

-- | Every <a>Process</a> action returns it's actual result wrapped in this
--   type. It will allow to signal errors as well as pass on normal results
--   such as incoming messages.
data ResumeProcess v

-- | The process is required to exit.
[ShutdownRequested] :: ResumeProcess v

-- | The process is required to exit from an error condition, that cannot
--   be recovered from.
[OnError] :: String -> ResumeProcess v

-- | The process may resume to do work, using the given result.
[ResumeWith] :: a -> ResumeProcess a

-- | This indicates that the action did not complete, and maybe retried
[RetryLastAction] :: ResumeProcess v

-- | Every function for <a>Process</a> things needs proxy for the low-level
--   effect list depending on the scheduler implementation. I don't know a
--   smarter way yet to do this.
data SchedulerProxy :: [Type -> Type] -> Type
[SchedulerProxy] :: SchedulerProxy q

-- | Return a <a>SchedulerProxy</a> for a <a>Process</a> effect.
thisSchedulerProxy :: Eff (Process r : r) (SchedulerProxy r)

-- | Execute a and action and resume the process, retry the action,
--   shutdown the process or return an error.
yieldAndCatchProcess :: forall q r v. (SetMember Process (Process q) r, HasCallStack) => SchedulerProxy q -> Eff r (ResumeProcess v) -> Eff r (Either String v)

-- | Send a message to a process addressed by the <a>ProcessId</a>. See
--   <a>SendMessage</a>.
sendMessage :: forall r q. (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> ProcessId -> Dynamic -> Eff r Bool

-- | Start a new process, the new process will execute an effect, the
--   function will return immediately with a <a>ProcessId</a>.
spawn :: forall r q. (HasCallStack, SetMember Process (Process q) r) => Eff (Process q : q) () -> Eff r ProcessId

-- | Block until a message was received.
receiveMessage :: forall r q. (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> Eff r Dynamic

-- | Receive and cast the message to some <a>Typeable</a> instance.
receiveMessageAs :: forall a r q. (HasCallStack, Typeable a, SetMember Process (Process q) r) => SchedulerProxy q -> Eff r a

-- | Enter a loop to receive messages and pass them to a callback, until
--   the function returns <a>False</a>.
receiveLoop :: forall r q. (SetMember Process (Process q) r, HasCallStack) => SchedulerProxy q -> (Either (Maybe String) Dynamic -> Eff r ()) -> Eff r ()

-- | Returns the <a>ProcessId</a> of the current process.
self :: (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> Eff r ProcessId

-- | Send a message to a process addressed by the <a>ProcessId</a>. See
--   <a>SendMessage</a>.
sendShutdown :: forall r q. (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> ProcessId -> Eff r Bool

-- | Exit the process with an error.
exitWithError :: forall r q a. (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> String -> Eff r a

-- | Exit the process.
exitNormally :: forall r q a. (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> Eff r a

-- | Thrown an error, can be caught by <a>catchRaisedError</a>.
raiseError :: forall r q b. (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> String -> Eff r b

-- | Catch and handle an error raised by <a>raiseError</a>. Works
--   independent of the handler implementation.
catchRaisedError :: forall r q w. (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> (String -> Eff r w) -> Eff r w -> Eff r w

-- | Like <a>catchRaisedError</a> it catches <a>raiseError</a>, but instead
--   of invoking a user provided handler, the result is wrapped into an
--   <a>Either</a>.
ignoreProcessError :: (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> Eff r a -> Eff r (Either String a)
instance GHC.Real.Real Control.Eff.Concurrent.Process.ProcessId
instance GHC.Real.Integral Control.Eff.Concurrent.Process.ProcessId
instance GHC.Enum.Enum Control.Eff.Concurrent.Process.ProcessId
instance GHC.Num.Num Control.Eff.Concurrent.Process.ProcessId
instance GHC.Enum.Bounded Control.Eff.Concurrent.Process.ProcessId
instance GHC.Classes.Ord Control.Eff.Concurrent.Process.ProcessId
instance GHC.Classes.Eq Control.Eff.Concurrent.Process.ProcessId
instance Data.Traversable.Traversable Control.Eff.Concurrent.Process.ResumeProcess
instance GHC.Classes.Ord v => GHC.Classes.Ord (Control.Eff.Concurrent.Process.ResumeProcess v)
instance GHC.Classes.Eq v => GHC.Classes.Eq (Control.Eff.Concurrent.Process.ResumeProcess v)
instance GHC.Show.Show v => GHC.Show.Show (Control.Eff.Concurrent.Process.ResumeProcess v)
instance GHC.Base.Functor Control.Eff.Concurrent.Process.ResumeProcess
instance Data.Foldable.Foldable Control.Eff.Concurrent.Process.ResumeProcess
instance GHC.Read.Read Control.Eff.Concurrent.Process.ProcessId
instance GHC.Show.Show Control.Eff.Concurrent.Process.ProcessId


-- | This module contains a mechanisms to specify what kind of messages a
--   process can receive and possible answer by sending a message back to
--   the orginator.
--   
--   A message can be either a blocking or a non-blocking request.
--   
--   The type magic in the <a>Api</a> type familiy allows to define a
--   related set of messages along with the corresponding responses.
--   
--   A process can <i>serve</i> a specific <a>Api</a> instance by using the
--   functions provided by the <a>Control.Eff.Concurrent.Api.Server</a>
--   module.
--   
--   To enable a process to use such a <i>service</i>, the functions
--   provided by the <a>Control.Eff.Concurrent.Api.Client</a> should be
--   used.
module Control.Eff.Concurrent.Api

-- | This data family defines an API, a communication interface description
--   between to processes, where one process acts as a <b>server</b> and
--   the other(s) as <b>client(s)</b>.
--   
--   The first parameter is usually a user defined phantom type that
--   identifies the <a>Api</a> instance.
--   
--   The second parameter specifies if a specific constructor of an
--   (GADT-like) <tt>Api</tt> instance is <a>Synchronous</a>, i.e. returns
--   a result and blocks the caller or if it is <a>Asynchronous</a>
--   
--   Example:
--   
--   <pre>
--   data BookShop deriving Typeable
--   
--   data instance Api BookShop r where
--     RentBook  :: BookId   -&gt; Api BookShop ('Synchronous (Either RentalError RentalId))
--     BringBack :: RentalId -&gt; Api BookShop 'Asynchronous
--   
--   type BookId = Int
--   type RentalId = Int
--   type RentalError = String
--   </pre>

-- | This <b>data kind</b> is used to indicate at the type level if a
--   specific constructor of an <tt>Api</tt> instance has a result for
--   which some caller has to wait, or if it is asynchronous.
data Synchronicity

-- | Blocking operation with a specific return type, e.g. <tt>('Synchronous
--   (Either RentalError RentalId))</tt>
Synchronous :: Type -> Synchronicity

-- | Non-blocking async operation
Asynchronous :: Synchronicity

-- | This is a tag-type that wraps around a <a>ProcessId</a> and holds an
--   <a>Api</a> index type.
newtype Server api
Server :: ProcessId -> Server api
[_fromServer] :: Server api -> ProcessId
fromServer :: forall api_ahBr api_ahLU. Iso (Server api_ahBr) (Server api_ahLU) ProcessId ProcessId

-- | Tag a <a>ProcessId</a> with an <a>Api</a> type index to mark it a
--   <a>Server</a> process handling that API
proxyAsServer :: proxy api -> ProcessId -> Server api

-- | Tag a <a>ProcessId</a> with an <a>Api</a> type index to mark it a
--   <a>Server</a> process handling that API
asServer :: forall api. ProcessId -> Server api
instance forall k (api :: k). GHC.Classes.Ord (Control.Eff.Concurrent.Api.Server api)
instance forall k (api :: k). GHC.Classes.Eq (Control.Eff.Concurrent.Api.Server api)
instance forall k (api :: k). GHC.Read.Read (Control.Eff.Concurrent.Api.Server api)
instance forall k (api :: k). Data.Typeable.Internal.Typeable api => GHC.Show.Show (Control.Eff.Concurrent.Api.Server api)


-- | Functions for <a>Api</a> clients.
--   
--   This modules is required to write clients that consume an <a>Api</a>.
module Control.Eff.Concurrent.Api.Client

-- | Send an <a>Api</a> request that has no return value and return as fast
--   as possible. The type signature enforces that the corresponding
--   <a>Api</a> clause is <a>Asynchronous</a>.
cast :: forall r q o. (HasCallStack, SetMember Process (Process q) r, Typeable o, Typeable (Api o  'Asynchronous)) => SchedulerProxy q -> Server o -> Api o  'Asynchronous -> Eff r ()

-- | Send an <a>Api</a> request that has no return value and return as fast
--   as possible. The type signature enforces that the corresponding
--   <a>Api</a> clause is <a>Asynchronous</a>. Return <tt>True</tt> if the
--   message was sent to the process. Note that this is totally not the
--   same as that the request was successfully handled. If that is
--   important, use <a>call</a> instead.
castChecked :: forall r q o. (HasCallStack, SetMember Process (Process q) r, Typeable o, Typeable (Api o  'Asynchronous)) => SchedulerProxy q -> Server o -> Api o  'Asynchronous -> Eff r Bool

-- | Send an <a>Api</a> request and wait for the server to return a result
--   value.
--   
--   The type signature enforces that the corresponding <a>Api</a> clause
--   is <a>Synchronous</a>.
call :: forall result api r q. (SetMember Process (Process q) r, Typeable api, Typeable (Api api ( 'Synchronous result)), Typeable result, HasCallStack) => SchedulerProxy q -> Server api -> Api api ( 'Synchronous result) -> Eff r result

-- | Like <a>cast</a> but take the <a>Server</a> from the reader provided
--   by <a>registerServer</a>.
castRegistered :: (Typeable o, ServesApi o r q) => SchedulerProxy q -> Api o  'Asynchronous -> Eff r ()

-- | Like <a>call</a> but take the <a>Server</a> from the reader provided
--   by <a>registerServer</a>.
callRegistered :: (Typeable reply, ServesApi o r q) => SchedulerProxy q -> Api o ( 'Synchronous reply) -> Eff r reply

-- | Like <a>callRegistered</a> but also catch errors raised if e.g. the
--   server crashed. By allowing <a>Alternative</a> instances to contain
--   the reply, application level errors can be combined with errors rising
--   from inter process communication.
callRegisteredA :: forall r q o f reply. (Alternative f, Typeable f, Typeable reply, ServesApi o r q) => SchedulerProxy q -> Api o ( 'Synchronous (f reply)) -> Eff r (f reply)

-- | Instead of passing around a <a>Server</a> value and passing to
--   functions like <a>cast</a> or <a>call</a>, a <a>Server</a> can
--   provided by a <a>Reader</a> effect, if there is only a <b>single
--   server</b> for a given <a>Api</a> instance. This type alias is
--   convenience to express that an effect has <a>Process</a> and a reader
--   for a <a>Server</a>.
type ServesApi o r q = (Typeable o, SetMember Process (Process q) r, Member (Reader (Server o)) r)

-- | Run a reader effect that contains <b>the one</b> server handling a
--   specific <a>Api</a> instance.
registerServer :: Server o -> Eff (Reader (Server o) : r) a -> Eff r a


-- | Add-ons to <a>Exception</a>
module Control.Eff.ExceptionExtra

-- | Catch an exception and return it in an <a>Either</a>.
try :: forall e r a. Member (Exc e) r => Eff r a -> Eff r (Either e a)

-- | Lift an IO action and catch all error using <a>try</a> then wrap the
--   <a>Exception</a> using a given wrapper function and rethrow it using
--   <a>throwError</a>.
liftRethrow :: forall proxy e r a. (Exception e, SetMember Lift (Lift IO) r, SetMember Exc (Exc e) r) => proxy e -> IO a -> Eff r a

-- | Run an effect with exceptions like <a>runError</a> and rethrow it as
--   <a>SomeException</a> using <a>throw</a>
runErrorRethrowIO :: forall e r a. (Exception e, SetMember Lift (Lift IO) r) => Eff (Exc e : r) a -> Eff r a

-- | Lift an IO action and catch all errors with <a>try</a> with a pure
--   handler.
liftCatch :: forall e r a. (HasCallStack, Exception e, SetMember Lift (Lift IO) r) => (e -> a) -> IO a -> Eff r a

-- | Lift an IO action and catch all errors with <a>try</a> with an effect
--   handler.
liftCatchEff :: forall e r a. (SetMember Lift (Lift IO) r, HasCallStack, Exception e) => (e -> Eff r a) -> IO a -> Eff r a

-- | Catch <a>Exception</a> thrown by an effect.
liftTry :: forall e r a. (HasCallStack, Exception e, SetMember Lift (Lift IO) r) => Eff r a -> Eff r (Either e a)

module Control.Eff.Interactive
data Interaction a
[PrintLine] :: String -> Interaction ()
[ReadLine] :: (String -> a) -> Interaction a
[Step] :: Interaction ()
printLine :: (Member (Program Interaction) r, HasCallStack) => String -> Eff r ()
printStep :: (Member (Program Interaction) r, HasCallStack) => String -> Eff r ()
promptStep :: (Member (Program Interaction) r, HasCallStack) => String -> (String -> a) -> Eff r a
step :: (Member (Program Interaction) r, HasCallStack) => Eff r ()
class Interactive f
singleSteps :: (Interactive f, Member (Program Interaction) r, HasCallStack) => f a -> Eff r a
interactiveProgram :: (HasCallStack, Member (Program Interaction) r, Interactive f) => Eff (Program f : r) a -> Eff r a
runInteractionIOE :: (SetMember Lift (Lift IO) r, HasCallStack) => Eff (Program Interaction : r) a -> Eff r a
runInteractionIO :: Eff '[Program Interaction, Lift IO] a -> IO a


-- | Functions to implement <a>Api</a> <b>servers</b>.
module Control.Eff.Concurrent.Api.Server

-- | Receive and process incoming requests until the process exits, using
--   an <a>ApiHandler</a>.
serve :: forall r q p. (Typeable p, SetMember Process (Process q) r, HasCallStack) => SchedulerProxy q -> ApiHandler p r -> Eff r ()

-- | A record of callbacks requests to a <i>server</i>, serving a specific
--   <a>Api</a> family instance.
data ApiHandler p r
[ApiHandler] :: {_handleCast :: HasCallStack => Api p  'Asynchronous -> Eff r ()  A cast will not return a result directly. This is used for async methods., _handleCall :: forall x. HasCallStack => Api p ( 'Synchronous x) -> (x -> Eff r Bool) -> Eff r ()  A call is a blocking operation, the caller is blocked until this handler calls the reply continuation., _handleTerminate :: HasCallStack => Maybe String -> Eff r ()  This callback is called with @Nothing@ if the process exits peacefully, or @Just "error message..."@ if the process exits with an error. This function is responsible to exit the process if necessary. The default behavior is defined in 'defaultTermination'.} -> ApiHandler p r

-- | A default handler to use in <a>_handleCall</a> in <a>ApiHandler</a>.
--   It will call <a>raiseError</a> with a nice error message.
unhandledCallError :: forall p x r q. (Show (Api p ( 'Synchronous x)), Typeable p, HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> Api p ( 'Synchronous x) -> (x -> Eff r Bool) -> Eff r ()

-- | A default handler to use in <a>_handleCast</a> in <a>ApiHandler</a>.
--   It will call <a>raiseError</a> with a nice error message.
unhandledCastError :: forall p r q. (Show (Api p  'Asynchronous), Typeable p, HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> Api p  'Asynchronous -> Eff r ()

-- | Exit the process either normally of the error message is
--   <tt>Nothing</tt> or with <a>exitWithError</a> otherwise.
defaultTermination :: forall q r. (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> Maybe String -> Eff r ()

-- | <a>serve</a> two <a>ApiHandler</a>s at once. The first handler is used
--   for termination handling.
serveBoth :: forall r q p1 p2. (Typeable p1, Typeable p2, SetMember Process (Process q) r, HasCallStack) => SchedulerProxy q -> ApiHandler p1 r -> ApiHandler p2 r -> Eff r ()

-- | <a>serve</a> three <a>ApiHandler</a>s at once. The first handler is
--   used for termination handling.
serve3 :: forall r q p1 p2 p3. (Typeable p1, Typeable p2, Typeable p3, SetMember Process (Process q) r, HasCallStack) => SchedulerProxy q -> ApiHandler p1 r -> ApiHandler p2 r -> ApiHandler p3 r -> Eff r ()

-- | The basic building block of the combination of <a>ApiHandler</a>s is
--   this function, which can not only be passed to <a>receiveLoop</a>, but
--   also throws an <a>UnhandledRequest</a> exception if <a>castMessage</a>
--   failed, such that multiple invokation of this function for different
--   <a>ApiHandler</a>s can be tried, by using <a>catchUnhandled</a>.
--   
--   <pre>
--   tryApiHandler px handlers1 message
--     `catchUnhandled`
--   tryApiHandler px handlers2
--     `catchUnhandled`
--   tryApiHandler px handlers3
--   </pre>
tryApiHandler :: forall r q p. (Typeable p, SetMember Process (Process q) r, HasCallStack) => SchedulerProxy q -> ApiHandler p r -> Dynamic -> Eff (Exc UnhandledRequest : r) ()

-- | An exception that is used by the mechanism that chains together
--   multiple different <a>ApiHandler</a> allowing a single process to
--   implement multiple <a>Api</a>s. This exception is thrown by
--   <a>castMessage</a>. This exception can be caught with
--   <a>catchUnhandled</a>, this way, several distinct <a>ApiHandler</a>
--   can be tried until one <i>fits</i> or until the <a>exitUnhandled</a>
--   is invoked.
data UnhandledRequest

-- | If <a>castMessage</a> failes to cast the message to a <a>Request</a>
--   for a certain <a>ApiHandler</a> it throws an <a>UnhandledRequest</a>
--   exception. That exception is caught by this function and the raw
--   message is given to the handler function. This is the basis for
--   chaining <a>ApiHandler</a>s.
catchUnhandled :: forall r a. (Member (Exc UnhandledRequest) r, HasCallStack) => Eff r a -> (Dynamic -> Eff r a) -> Eff r a

-- | Catch <a>UnhandledRequest</a>s and terminate the process with an
--   error, if necessary.
ensureAllHandled :: forall r q. (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> Eff (Exc UnhandledRequest : r) () -> Eff r ()

-- | Cast a <a>Dynamic</a> value, and if that fails, throw an
--   <a>UnhandledRequest</a> error.
castMessage :: forall r a. (HasCallStack, Typeable a, Member (Exc UnhandledRequest) r) => Dynamic -> Eff r a

-- | If an incoming message could not be casted to a <a>Request</a>
--   corresponding to an <a>ApiHandler</a> (e.g. with <a>castMessage</a>)
--   one should use this function to exit the process with a corresponding
--   error.
exitUnhandled :: forall r q. (SetMember Process (Process q) r, HasCallStack) => SchedulerProxy q -> Dynamic -> Eff r ()


-- | A logging effect based on <a>MonadLog</a>.
module Control.Eff.Log

-- | Logging effect type, parameterized by a log message type.
data Logs message a
[LogMsg] :: message -> Logs message ()

-- | Log a message.
logMsg :: Member (Logs m) r => m -> Eff r ()

-- | Change, add or remove log messages.
--   
--   Requirements:
--   
--   <ul>
--   <li>All log meta data for typical prod code can be added without
--   changing much of the code</li>
--   <li>Add timestamp to a log messages of a sub-computation.</li>
--   <li>Write some messages to a file.</li>
--   <li>Log something extra, e.g. runtime memory usage in load tests</li>
--   </ul>
--   
--   Approach: Install a callback that sneaks into to log message
--   sending/receiving, to intercept the messages and execute some code and
--   then return a new message.
foldLog :: forall r m a. Member (Logs m) r => (m -> Eff r ()) -> Eff r a -> Eff r a

-- | Change, add or remove log messages without side effects, faster than
--   <a>foldLog</a>.
--   
--   Requirements:
--   
--   <ul>
--   <li>Tests run fast in unit tests so travis won't time out</li>
--   <li>Drop debug logs</li>
--   <li><i>Grep like</i> log filtering</li>
--   </ul>
--   
--   Approach: Install a callback that sneaks into to log message
--   sending/receiving, to intercept the messages and execute some code and
--   then return a new message.
foldLogFast :: forall r m a f. (Foldable f, Member (Logs m) r) => (m -> f m) -> Eff r a -> Eff r a

-- | Capture the logs in a <a>Seq</a>.
captureLogs :: Eff (Logs message : r) a -> Eff r (a, Seq message)

-- | Throw away all log messages.
ignoreLogs :: Eff (Logs message : r) a -> Eff r a

-- | Handle <a>Logs</a> effects using <a>LoggingT</a> <a>Handler</a>s.
handleLogsWith :: forall m r message a. (Monad m, SetMember Lift (Lift m) r) => Eff (Logs message : r) a -> (forall b. (Handler m message -> m b) -> m b) -> Eff r a

-- | A log channel processes logs from the <a>Logs</a> effect by en-queuing
--   them in a shared queue read from a seperate processes. A channel can
--   contain log message filters.
data LogChannel message

-- | Send the log messages to a <a>LogChannel</a>.
logToChannel :: forall r message a. (SetMember Lift (Lift IO) r) => LogChannel message -> Eff (Logs message : r) a -> Eff r a

-- | Create a <a>LogChannel</a> that will discard all messages sent via
--   <tt>forwardLogstochannel</tt> or <a>logChannelPutIO</a>.
noLogger :: LogChannel message

-- | Fork a new process, that applies a monadic action to all log messages
--   sent via <a>logToChannel</a> or <a>logChannelPutIO</a>.
forkLogger :: forall message. (Typeable message, Show message) => Int -> (message -> IO ()) -> Maybe message -> IO (LogChannel message)

-- | Filter logs sent to a <a>LogChannel</a> using a predicate.
filterLogChannel :: (message -> Bool) -> LogChannel message -> LogChannel message

-- | Close a log channel created by e.g. <a>forkLogger</a>. Message already
--   enqueue are handled, as well as an optional final message. Subsequent
--   log message will not be handled anymore. If the log channel must be
--   closed immediately, use <a>killLogChannel</a> instead.
joinLogChannel :: (Show message, Typeable message) => Maybe message -> LogChannel message -> IO ()

-- | Close a log channel quickly, without logging messages already in the
--   queue. Subsequent logging requests will not be handled anymore. If the
--   log channel must be closed without loosing any messages, use
--   <a>joinLogChannel</a> instead.
killLogChannel :: (Show message, Typeable message) => Maybe message -> LogChannel message -> IO ()

-- | Run an action and close a <a>LogChannel</a> created by
--   <a>noLogger</a>, <a>forkLogger</a> or <a>filterLogChannel</a>
--   afterwards using <a>joinLogChannel</a>. If a <a>SomeException</a> was
--   thrown, the log channel is killed with <a>killLogChannel</a>, and the
--   exception is re-thrown.
closeLogChannelAfter :: (Show message, Typeable message, IsString message) => Maybe message -> LogChannel message -> IO a -> IO a

-- | Wrap <a>LogChannel</a> creation and destruction around a monad action
--   in <a>bracket</a>y manner. This function uses <a>joinLogChannel</a>,
--   so en-queued messages are flushed on exit. The resulting action in in
--   the <a>LoggingT</a> monad, which is essentially a reader for the log
--   handler function.
logChannelBracket :: (Show message, Typeable message) => Int -> Maybe message -> Maybe message -> (LogChannel message -> IO a) -> LoggingT message IO a

-- | Enqueue a log message into a log channel
logChannelPutIO :: LogChannel message -> message -> IO ()
instance GHC.Show.Show m => GHC.Show.Show (Control.Eff.Log.KillLogChannelException m)
instance GHC.Show.Show m => GHC.Show.Show (Control.Eff.Log.JoinLogChannelException m)
instance (Data.Typeable.Internal.Typeable m, GHC.Show.Show m) => GHC.Exception.Exception (Control.Eff.Log.KillLogChannelException m)
instance (Data.Typeable.Internal.Typeable m, GHC.Show.Show m) => GHC.Exception.Exception (Control.Eff.Log.JoinLogChannelException m)


-- | A coroutine based, single threaded scheduler for <a>Process</a>es.
module Control.Eff.Concurrent.Process.SingleThreadedScheduler

-- | Execute a <a>Process</a> in the current thread, all child processes
--   spawned by <a>spawn</a> will be executed concurrently using a
--   co-routine based, round-robin scheduler.
schedule :: forall r. Eff (Process r : r) () -> Eff r ()

-- | Execute a <a>Process</a> using <a>schedule</a> on top of <a>Lift</a>
--   <tt>IO</tt> and <a>Logs</a> <tt>String</tt> effects.
defaultMain :: HasCallStack => Eff '[Process '[Logs String, Lift IO], Logs String, Lift IO] () -> IO ()

-- | A <a>SchedulerProxy</a> for <a>LoggingAndIo</a>.
singleThreadedIoScheduler :: SchedulerProxy LoggingAndIo

-- | The concrete list of <a>Eff</a>ects for running this pure scheduler on
--   <tt>IO</tt> and with string logging.
type LoggingAndIo = '[Logs String, Lift IO]


-- | Implement Erlang style message passing concurrency.
--   
--   This handles the <tt>MessagePassing</tt> and <a>Process</a> effects,
--   using <a>TQueue</a>s and <a>forkIO</a>.
--   
--   This aims to be a pragmatic implementation, so even logging is
--   supported.
--   
--   At the core is a <i>main process</i> that enters <a>schedule</a> and
--   creates all of the internal state stored in <a>TVar</a>s to manage
--   processes with message queues.
--   
--   The <a>Eff</a> handler for <a>Process</a> and <tt>MessagePassing</tt>
--   use are implemented and available through <a>spawn</a>.
--   
--   <a>spawn</a> uses <a>forkFinally</a> and <a>TQueue</a>s and tries to
--   catch most exceptions.
module Control.Eff.Concurrent.Process.ForkIOScheduler

-- | This is the main entry point to running a message passing concurrency
--   application. This function takes a <a>Process</a> on top of the
--   <a>SchedulerIO</a> effect and a <a>LogChannel</a> for concurrent
--   logging.
schedule :: Eff (ConsProcess SchedulerIO) () -> LogChannel String -> IO ()

-- | Start the message passing concurrency system then execute a
--   <a>Process</a> on top of <a>SchedulerIO</a> effect. All logging is
--   sent to standard output.
defaultMain :: Eff (ConsProcess SchedulerIO) () -> IO ()

-- | Start the message passing concurrency system then execute a
--   <a>Process</a> on top of <a>SchedulerIO</a> effect. All logging is
--   sent to standard output.
defaultMainWithLogChannel :: LogChannel String -> Eff (ConsProcess SchedulerIO) () -> IO ()

-- | A sum-type with errors that can occur when scheduleing messages.
data SchedulerError

-- | No <a>ProcessInfo</a> was found for a <a>ProcessId</a> during internal
--   processing. NOTE: This is **ONLY** caused by internal errors, probably
--   by an incorrect <tt>MessagePassing</tt> handler in this module.
--   **Sending a message to a process ALWAYS succeeds!** Even if the
--   process does not exist.
ProcessNotFound :: ProcessId -> SchedulerError

-- | A process called <a>raiseError</a>.
ProcessRaisedError :: String -> SchedulerError

-- | A process called <a>exitWithError</a>.
ProcessExitError :: String -> SchedulerError

-- | A process exits.
ProcessShuttingDown :: SchedulerError

-- | An action was not performed while the scheduler was exiting.
SchedulerShuttingDown :: SchedulerError

-- | The concrete list of <a>Eff</a>ects for this scheduler implementation.
--   See HasSchedulerIO
type SchedulerIO = '[Reader SchedulerVar, Logs String, Lift IO]

-- | A <a>SchedulerProxy</a> for <a>SchedulerIO</a>
forkIoScheduler :: SchedulerProxy SchedulerIO

-- | An alias for the constraints for the effects essential to this
--   scheduler implementation, i.e. these effects allow <a>spawn</a>ing new
--   <a>Process</a>es. See SchedulerIO
type HasSchedulerIO r = (HasCallStack, SetMember Lift (Lift IO) r, Member (Logs String) r, Member (Reader SchedulerVar) r)
instance GHC.Show.Show Control.Eff.Concurrent.Process.ForkIOScheduler.SchedulerError
instance GHC.Exception.Exception Control.Eff.Concurrent.Process.ForkIOScheduler.SchedulerError
instance GHC.Show.Show Control.Eff.Concurrent.Process.ForkIOScheduler.ProcessInfo


-- | Observer Effects
--   
--   This module supports the implementation of observers and observables.
--   One use case is event propagation. The tools in this module are
--   tailored towards <a>Api</a> servers/clients.
module Control.Eff.Concurrent.Api.Observer

-- | An <a>Api</a> index that support observation of the another <a>Api</a>
--   that is <a>Observable</a>.
class (Typeable p, Observable o) => Observer p o

-- | Wrap the <a>Observation</a> and the <a>ProcessId</a> (i.e. the
--   <a>Server</a>) that caused the observation into a <a>Api</a> value
--   that the <a>Observable</a> understands.
observationMessage :: Observer p o => Server o -> Observation o -> Api p  'Asynchronous

-- | An <a>Api</a> index that supports registration and de-registration of
--   <a>Observer</a>s.
class (Typeable o, Typeable (Observation o)) => Observable o where {
    data family Observation o;
}

-- | Return the <a>Api</a> value for the <tt>cast_</tt> that registeres an
--   observer
registerObserverMessage :: Observable o => SomeObserver o -> Api o  'Asynchronous

-- | Return the <a>Api</a> value for the <tt>cast_</tt> that de-registeres
--   an observer
forgetObserverMessage :: Observable o => SomeObserver o -> Api o  'Asynchronous

-- | Send an <a>Observation</a> to an <a>Observer</a>
notifyObserver :: (SetMember Process (Process q) r, Observable o, Observer p o, HasCallStack) => SchedulerProxy q -> Server p -> Server o -> Observation o -> Eff r ()

-- | Send the <a>registerObserverMessage</a>
registerObserver :: (SetMember Process (Process q) r, Observable o, Observer p o, HasCallStack) => SchedulerProxy q -> Server p -> Server o -> Eff r ()

-- | Send the <a>forgetObserverMessage</a>
forgetObserver :: (SetMember Process (Process q) r, Observable o, Observer p o) => SchedulerProxy q -> Server p -> Server o -> Eff r ()

-- | An existential wrapper around a <a>Server</a> of an <a>Observer</a>.
--   Needed to support different types of observers to observe the same
--   <a>Observable</a> in a general fashion.
data SomeObserver o
[SomeObserver] :: (Show (Server p), Typeable p, Observer p o) => Server p -> SomeObserver o

-- | Send an <a>Observation</a> to <a>SomeObserver</a>.
notifySomeObserver :: (SetMember Process (Process q) r, Observable o, HasCallStack) => SchedulerProxy q -> Server o -> Observation o -> SomeObserver o -> Eff r ()

-- | Internal state for <tt>manageobservers</tt>
data Observers o

-- | Keep track of registered <a>Observer</a>s Observers can be added and
--   removed, and an <a>Observation</a> can be sent to all registerd
--   observers at once.
manageObservers :: Eff (State (Observers o) : r) a -> Eff r a

-- | Add an <a>Observer</a> to the <a>Observers</a> managed by
--   <a>manageObservers</a>.
addObserver :: (SetMember Process (Process q) r, Member (State (Observers o)) r, Observable o) => SomeObserver o -> Eff r ()

-- | Delete an <a>Observer</a> from the <a>Observers</a> managed by
--   <a>manageObservers</a>.
removeObserver :: (SetMember Process (Process q) r, Member (State (Observers o)) r, Observable o) => SomeObserver o -> Eff r ()

-- | Send an <a>Observation</a> to all <a>SomeObserver</a>s in the
--   <a>Observers</a> state.
notifyObservers :: forall o r q. (Observable o, SetMember Process (Process q) r, Member (State (Observers o)) r) => SchedulerProxy q -> Observation o -> Eff r ()

-- | An <a>Observer</a> that schedules the observations to an effectful
--   callback.
data CallbackObserver o

-- | Start a new process for an <a>Observer</a> that schedules all
--   observations to an effectful callback.
spawnCallbackObserver :: forall o r q. (SetMember Process (Process q) r, Typeable o, Show (Observation o), Observable o, Member (Logs String) q) => SchedulerProxy q -> (Server o -> Observation o -> Eff (Process q : q) Bool) -> Eff r (Server (CallbackObserver o))
instance GHC.Show.Show (Control.Eff.Concurrent.Api.Observer.SomeObserver o)
instance GHC.Show.Show (Control.Eff.Concurrent.Api.Observer.Observation o) => GHC.Show.Show (Control.Eff.Concurrent.Api.Api (Control.Eff.Concurrent.Api.Observer.CallbackObserver o) r)
instance Control.Eff.Concurrent.Api.Observer.Observable o => Control.Eff.Concurrent.Api.Observer.Observer (Control.Eff.Concurrent.Api.Observer.CallbackObserver o) o
instance GHC.Classes.Ord (Control.Eff.Concurrent.Api.Observer.SomeObserver o)
instance GHC.Classes.Eq (Control.Eff.Concurrent.Api.Observer.SomeObserver o)