Control.Eff.Concurrent.Process

The message passing effect.

This module describes an abstract message passing effect, and a process effect, mimicking Erlang's process and message semantics.

Two scheduler implementations for the Process effect are provided:

• A scheduler using forkIO, i.e. relying on the multi threaded GHC runtime: Control.Eff.Concurrent.Process.ForkIOScheduler
• And a pure(rer) coroutine based scheduler in: Control.Eff.Concurrent.Process.SingleThreadedScheduler

Process Effect

Effect Type Handling

data Process (r :: [Type -> Type]) b where

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:

• fair scheduling
• sending a message does not block
• receiving a message does block
• spawning a child blocks only a very moment
• a newly spawned process shall be scheduled before the parent process after
• the spawnRaw
• when the first process exists, all process should be killed immediately

Constructors

FlushMessages :: Process r (ResumeProcess [Dynamic])

Remove all messages from the process' message queue

YieldProcess :: Process r (ResumeProcess ())

In cooperative schedulers, this will give processing time to the scheduler. Every other operation implicitly serves the same purpose.

Since: 0.12.0

SelfPid :: Process r (ResumeProcess ProcessId)

Return the current ProcessId

Spawn :: Eff (Process r ': r) () -> Process r (ResumeProcess ProcessId)

Start a new process, the new process will execute an effect, the function will return immediately with a ProcessId.

SpawnLink :: Eff (Process r ': r) () -> Process r (ResumeProcess ProcessId)

Start a new process, and Link to it .

Since: 0.12.0

GetProcessState :: ProcessId -> Process r (ResumeProcess (Maybe ProcessState))

Get the process state (or Nothing if the process is dead)

Shutdown :: ExitReason NoRecovery -> Process r a

Shutdown the process; irregardles of the exit reason, this function never returns,

SendShutdown :: ProcessId -> ExitReason NoRecovery -> Process r (ResumeProcess ())

Raise an error, that can be handled.

SendInterrupt :: ProcessId -> InterruptReason -> Process r (ResumeProcess ())

Request that another a process interrupts. The targeted process is interrupted and gets an Interrupted, the target process may decide to ignore the interrupt and continue as if nothing happened.

SendMessage :: ProcessId -> Dynamic -> Process r (ResumeProcess ())

Send a message to a process addressed by the ProcessId. 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.

ReceiveSelectedMessage :: forall r a. MessageSelector a -> Process r (ResumeProcess a)

Receive a message that matches a criterium. This should block until an a message was received. The message is returned as a ProcessMessage value. The function should also return if an exception was caught or a shutdown was requested.

MakeReference :: Process r (ResumeProcess Int)

Generate a unique Int for the current process.

Monitor :: ProcessId -> Process r (ResumeProcess MonitorReference)

Monitor another process. When the monitored process exits a ProcessDown is sent to the calling process. The return value is a unique identifier for that monitor. There can be multiple monitors on the same process, and a message for each will be sent. If the process is already dead, the ProcessDown message will be sent immediately, w.thout exit reason

Since: 0.12.0

Demonitor :: MonitorReference -> Process r (ResumeProcess ())

Remove a monitor.

Since: 0.12.0

Link :: ProcessId -> Process r (ResumeProcess ())

Connect the calling process to another process, such that if one of the processes crashes (i.e. isCrash returns True), the other is shutdown with the ProcessExitReaon LinkedProcessCrashed.

Since: 0.12.0

Unlink :: ProcessId -> Process r (ResumeProcess ())

Unlink the calling proccess from the other process.

Since: 0.12.0

Instances

Show (Process r b)

Defined in Control.Eff.Concurrent.Process

Methods

showsPrec :: Int -> Process r b -> ShowS

show :: Process r b -> String

showList :: [Process r b] -> ShowS

ProcessId Type

newtype ProcessId

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.

Constructors

ProcessId

Fields

• _fromProcessId :: Int

Instances

Bounded ProcessId

Defined in Control.Eff.Concurrent.Process

Methods

minBound :: ProcessId

maxBound :: ProcessId

Enum ProcessId

Defined in Control.Eff.Concurrent.Process

Methods

succ :: ProcessId -> ProcessId

pred :: ProcessId -> ProcessId

toEnum :: Int -> ProcessId

fromEnum :: ProcessId -> Int

enumFrom :: ProcessId -> [ProcessId]

enumFromThen :: ProcessId -> ProcessId -> [ProcessId]

enumFromTo :: ProcessId -> ProcessId -> [ProcessId]

enumFromThenTo :: ProcessId -> ProcessId -> ProcessId -> [ProcessId]

Eq ProcessId

Defined in Control.Eff.Concurrent.Process

Methods

(==) :: ProcessId -> ProcessId -> Bool

(/=) :: ProcessId -> ProcessId -> Bool

Integral ProcessId

Defined in Control.Eff.Concurrent.Process

Methods

quot :: ProcessId -> ProcessId -> ProcessId

rem :: ProcessId -> ProcessId -> ProcessId

div :: ProcessId -> ProcessId -> ProcessId

mod :: ProcessId -> ProcessId -> ProcessId

quotRem :: ProcessId -> ProcessId -> (ProcessId, ProcessId)

divMod :: ProcessId -> ProcessId -> (ProcessId, ProcessId)

toInteger :: ProcessId -> Integer

Num ProcessId

Defined in Control.Eff.Concurrent.Process

Methods

(+) :: ProcessId -> ProcessId -> ProcessId

(-) :: ProcessId -> ProcessId -> ProcessId

(*) :: ProcessId -> ProcessId -> ProcessId

negate :: ProcessId -> ProcessId

abs :: ProcessId -> ProcessId

signum :: ProcessId -> ProcessId

fromInteger :: Integer -> ProcessId

Ord ProcessId

Defined in Control.Eff.Concurrent.Process

Methods

compare :: ProcessId -> ProcessId -> Ordering

(<) :: ProcessId -> ProcessId -> Bool

(<=) :: ProcessId -> ProcessId -> Bool

(>) :: ProcessId -> ProcessId -> Bool

(>=) :: ProcessId -> ProcessId -> Bool

max :: ProcessId -> ProcessId -> ProcessId

min :: ProcessId -> ProcessId -> ProcessId

Read ProcessId

Defined in Control.Eff.Concurrent.Process

Methods

readsPrec :: Int -> ReadS ProcessId

readList :: ReadS [ProcessId]

readPrec :: ReadPrec ProcessId

readListPrec :: ReadPrec [ProcessId]

Real ProcessId

Defined in Control.Eff.Concurrent.Process

Methods

toRational :: ProcessId -> Rational

Show ProcessId

Defined in Control.Eff.Concurrent.Process

Methods

showsPrec :: Int -> ProcessId -> ShowS

show :: ProcessId -> String

showList :: [ProcessId] -> ShowS

NFData ProcessId

Defined in Control.Eff.Concurrent.Process

Methods

rnf :: ProcessId -> ()

fromProcessId :: Iso' ProcessId Int

type ConsProcess r = Process r ': r

Cons Process onto a list of effects.

data ResumeProcess v where

Every Process 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.

Constructors

Interrupted :: InterruptReason -> ResumeProcess v

The current operation of the process was interrupted with a ExitReason. If isRecoverable holds for the given reason, the process may choose to continue.

ResumeWith :: a -> ResumeProcess a

The process may resume to do work, using the given result.

Instances

NFData1 ResumeProcess

Defined in Control.Eff.Concurrent.Process

Methods

liftRnf :: (a -> ()) -> ResumeProcess a -> ()

Show v => Show (ResumeProcess v)

Defined in Control.Eff.Concurrent.Process

Methods

showsPrec :: Int -> ResumeProcess v -> ShowS

show :: ResumeProcess v -> String

showList :: [ResumeProcess v] -> ShowS

Generic (ResumeProcess v)

Defined in Control.Eff.Concurrent.Process

Associated Types

type Rep (ResumeProcess v) :: Type -> Type

Methods

from :: ResumeProcess v -> Rep (ResumeProcess v) x

to :: Rep (ResumeProcess v) x -> ResumeProcess v

NFData a => NFData (ResumeProcess a)

Defined in Control.Eff.Concurrent.Process

Methods

rnf :: ResumeProcess a -> ()

Generic1 ResumeProcess

Defined in Control.Eff.Concurrent.Process

Associated Types

type Rep1 ResumeProcess :: k -> Type

Methods

from1 :: ResumeProcess a -> Rep1 ResumeProcess a

to1 :: Rep1 ResumeProcess a -> ResumeProcess a

type Rep (ResumeProcess v)

Defined in Control.Eff.Concurrent.Process

type Rep (ResumeProcess v) = D1 (MetaData "ResumeProcess" "Control.Eff.Concurrent.Process" "extensible-effects-concurrent-0.14.0-KhFRpYG1b4SDYIjm4HuI8R" False) (C1 (MetaCons "Interrupted" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 InterruptReason)) :+: C1 (MetaCons "ResumeWith" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 v)))

type Rep1 ResumeProcess

Defined in Control.Eff.Concurrent.Process

type Rep1 ResumeProcess = D1 (MetaData "ResumeProcess" "Control.Eff.Concurrent.Process" "extensible-effects-concurrent-0.14.0-KhFRpYG1b4SDYIjm4HuI8R" False) (C1 (MetaCons "Interrupted" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 InterruptReason)) :+: C1 (MetaCons "ResumeWith" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) Par1))

Scheduler Effect Identification

data SchedulerProxy :: [Type -> Type] -> Type where

Every function for Process things needs such a proxy value for the low-level effect list, i.e. the effects identified by r in Process r : r, this might be dependent on the scheduler implementation.

Constructors

SchedulerProxy :: SchedulerProxy q

Tell the typechecker what effects we have below Process

SP :: SchedulerProxy q

Like SchedulerProxy but shorter

Scheduler :: SchedulerProxy q

Like SP but different

type HasScheduler q = ?_schedulerProxy :: SchedulerProxy q

A constraint for the implicit SchedulerProxy parameter. Use getSchedulerProxy to query it. _EXPERIMENTAL_

Since: 0.12.0

getSchedulerProxy :: HasScheduler q => SchedulerProxy q

Get access to the SchedulerProxy for the current scheduler effects. _EXPERIMENTAL_

Since: 0.12.0

withSchedulerProxy :: SchedulerProxy q -> (HasScheduler q => a) -> a

Set the SchedulerProxy to use, this satisfies HasScheduler . _EXPERIMENTAL_

Since: 0.12.0

thisSchedulerProxy :: Eff (Process r ': r) (SchedulerProxy r)

Return a SchedulerProxy for a Process effect.

Process State

data ProcessState

The state that a Process is currently in.

Constructors

ProcessBooting

The process has just been started but not called handleProcess yet.

ProcessIdle

The process yielded it's timeslice

ProcessBusy

The process is busy with non-blocking

ProcessBusySending

The process is busy with sending a message

ProcessBusySendingShutdown

The process is busy with killing

ProcessBusySendingInterrupt

The process is busy with killing

ProcessBusyReceiving

The process blocked by a receiveAnyMessage

ProcessBusyLinking

The process blocked by a linkProcess

ProcessBusyUnlinking

The process blocked by a unlinkProcess

ProcessBusyMonitoring

The process blocked by a monitor

ProcessBusyDemonitoring

The process blocked by a demonitor

ProcessInterrupted

The process was interrupted

ProcessShuttingDown

The process was shutdown or crashed

Instances

Enum ProcessState

Defined in Control.Eff.Concurrent.Process

Methods

succ :: ProcessState -> ProcessState

pred :: ProcessState -> ProcessState

toEnum :: Int -> ProcessState

fromEnum :: ProcessState -> Int

enumFrom :: ProcessState -> [ProcessState]

enumFromThen :: ProcessState -> ProcessState -> [ProcessState]

enumFromTo :: ProcessState -> ProcessState -> [ProcessState]

enumFromThenTo :: ProcessState -> ProcessState -> ProcessState -> [ProcessState]

Eq ProcessState

Defined in Control.Eff.Concurrent.Process

Methods

(==) :: ProcessState -> ProcessState -> Bool

(/=) :: ProcessState -> ProcessState -> Bool

Ord ProcessState

Defined in Control.Eff.Concurrent.Process

Methods

compare :: ProcessState -> ProcessState -> Ordering

(<) :: ProcessState -> ProcessState -> Bool

(<=) :: ProcessState -> ProcessState -> Bool

(>) :: ProcessState -> ProcessState -> Bool

(>=) :: ProcessState -> ProcessState -> Bool

max :: ProcessState -> ProcessState -> ProcessState

min :: ProcessState -> ProcessState -> ProcessState

Read ProcessState

Defined in Control.Eff.Concurrent.Process

Methods

readsPrec :: Int -> ReadS ProcessState

readList :: ReadS [ProcessState]

readPrec :: ReadPrec ProcessState

readListPrec :: ReadPrec [ProcessState]

Show ProcessState

Defined in Control.Eff.Concurrent.Process

Methods

showsPrec :: Int -> ProcessState -> ShowS

show :: ProcessState -> String

showList :: [ProcessState] -> ShowS

Generic ProcessState

Defined in Control.Eff.Concurrent.Process

Associated Types

type Rep ProcessState :: Type -> Type

Methods

from :: ProcessState -> Rep ProcessState x

to :: Rep ProcessState x -> ProcessState

Default ProcessState

Defined in Control.Eff.Concurrent.Process

Methods

def :: ProcessState

NFData ProcessState

Defined in Control.Eff.Concurrent.Process

Methods

rnf :: ProcessState -> ()

type Rep ProcessState

Defined in Control.Eff.Concurrent.Process

type Rep ProcessState = D1 (MetaData "ProcessState" "Control.Eff.Concurrent.Process" "extensible-effects-concurrent-0.14.0-KhFRpYG1b4SDYIjm4HuI8R" False) (((C1 (MetaCons "ProcessBooting" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "ProcessIdle" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "ProcessBusy" PrefixI False) (U1 :: Type -> Type))) :+: (C1 (MetaCons "ProcessBusySending" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "ProcessBusySendingShutdown" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "ProcessBusySendingInterrupt" PrefixI False) (U1 :: Type -> Type)))) :+: ((C1 (MetaCons "ProcessBusyReceiving" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "ProcessBusyLinking" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "ProcessBusyUnlinking" PrefixI False) (U1 :: Type -> Type))) :+: ((C1 (MetaCons "ProcessBusyMonitoring" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "ProcessBusyDemonitoring" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "ProcessInterrupted" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "ProcessShuttingDown" PrefixI False) (U1 :: Type -> Type)))))

Yielding

yieldProcess :: forall r q. (SetMember Process (Process q) r, HasCallStack, Member Interrupts r) => SchedulerProxy q -> Eff r ()

Use executeAndResumeOrExit to execute YieldProcess. Refer to YieldProcess for more information.

Sending Messages

sendMessage :: forall r q o. (SetMember Process (Process q) r, HasCallStack, Member Interrupts r, Typeable o) => SchedulerProxy q -> ProcessId -> o -> Eff r ()

Send a message to a process addressed by the ProcessId. See SendMessage.

sendAnyMessage :: forall r q. (SetMember Process (Process q) r, HasCallStack, Member Interrupts r) => SchedulerProxy q -> ProcessId -> Dynamic -> Eff r ()

Send a Dynamic value to a process addressed by the ProcessId. See SendMessage.

sendShutdown :: forall r q. (SetMember Process (Process q) r, HasCallStack, Member Interrupts r) => SchedulerProxy q -> ProcessId -> ExitReason NoRecovery -> Eff r ()

Exit a process addressed by the ProcessId. The process will exit, it might do some cleanup, but is ultimately unrecoverable. See SendShutdown.

sendInterrupt :: forall r q. (SetMember Process (Process q) r, HasCallStack, Member Interrupts r) => SchedulerProxy q -> ProcessId -> InterruptReason -> Eff r ()

Interrupts a process addressed by the ProcessId. The process might exit, or it may continue. | Like sendInterrupt, but also return True iff the process to exit exists.

Utilities

makeReference :: (HasCallStack, SetMember Process (Process q) r, Member Interrupts r) => SchedulerProxy q -> Eff r Int

Generate a unique Int for the current process.

Receiving Messages

receiveMessage :: forall a r q. (HasCallStack, Typeable a, Show a, SetMember Process (Process q) r, Member Interrupts r) => SchedulerProxy q -> Eff r a

Receive and cast the message to some Typeable instance. See ReceiveSelectedMessage for more documentation. This will wait for a message of the return type using receiveSelectedMessage

receiveSelectedMessage :: forall r q a. (HasCallStack, Show a, SetMember Process (Process q) r, Member Interrupts r) => SchedulerProxy q -> MessageSelector a -> Eff r a

Block until a message was received, that is not Nothing after applying a callback to it. See ReceiveSelectedMessage for more documentation.

flushMessages :: forall r q. (HasCallStack, SetMember Process (Process q) r, Member Interrupts r, HasScheduler q) => Eff r [Dynamic]

Remove and return all messages currently enqueued in the process message queue.

Since: 0.12.0

receiveAnyMessage :: forall r q. (HasCallStack, SetMember Process (Process q) r, Member Interrupts r) => SchedulerProxy q -> Eff r Dynamic

Block until a message was received. See ReceiveSelectedMessage for more documentation.

receiveLoop :: forall r q a endOfLoopResult. (SetMember Process (Process q) r, HasCallStack, Typeable a) => SchedulerProxy q -> (Either InterruptReason a -> Eff r (Maybe endOfLoopResult)) -> Eff r endOfLoopResult

Like receiveSelectedLoop but refined to casting to a specific Typeable using selectMessageLazy.

receiveSelectedLoop :: forall r q a endOfLoopResult. (SetMember Process (Process q) r, HasCallStack) => SchedulerProxy q -> MessageSelector a -> (Either InterruptReason a -> Eff r (Maybe endOfLoopResult)) -> Eff r endOfLoopResult

Enter a loop to receive messages and pass them to a callback, until the function returns Just a result. Only the messages of the given type will be received. If the process is interrupted by an exception of by a SendShutdown from another process, with an exit reason that satisfies isRecoverable, then the callback will be invoked with Left ProcessExitReaon, otherwise the process will be exited with the same reason using exitBecause. See also ReceiveSelectedMessage for more documentation.

receiveAnyLoop :: forall r q endOfLoopResult. (SetMember Process (Process q) r, HasCallStack) => SchedulerProxy q -> (Either InterruptReason Dynamic -> Eff r (Maybe endOfLoopResult)) -> Eff r endOfLoopResult

Like receiveSelectedLoop but not selective. See also selectAnyMessageLazy, receiveSelectedLoop.

Selecting Messages to Receive

data MessageSelector a

A function that deciced if the next message will be received by ReceiveSelectedMessage. It conveniently is an instance of Alternative so the message selector can be combined: > > selectInt :: MessageSelector Int > selectInt = selectMessage > > selectString :: MessageSelector String > selectString = selectMessage > > selectIntOrString :: MessageSelector (Either Int String) > selectIntOrString = > Left $ selectTimeout| Right $ selectString

Instances

Functor MessageSelector

Defined in Control.Eff.Concurrent.Process

Methods

fmap :: (a -> b) -> MessageSelector a -> MessageSelector b

(<$) :: a -> MessageSelector b -> MessageSelector a

Applicative MessageSelector

Defined in Control.Eff.Concurrent.Process

Methods

pure :: a -> MessageSelector a

(<*>) :: MessageSelector (a -> b) -> MessageSelector a -> MessageSelector b

liftA2 :: (a -> b -> c) -> MessageSelector a -> MessageSelector b -> MessageSelector c

(*>) :: MessageSelector a -> MessageSelector b -> MessageSelector b

(<*) :: MessageSelector a -> MessageSelector b -> MessageSelector a

Alternative MessageSelector

Defined in Control.Eff.Concurrent.Process

Methods

empty :: MessageSelector a

(<|>) :: MessageSelector a -> MessageSelector a -> MessageSelector a

some :: MessageSelector a -> MessageSelector [a]

many :: MessageSelector a -> MessageSelector [a]

Semigroup a => Semigroup (MessageSelector a)

Defined in Control.Eff.Concurrent.Process

Methods

(<>) :: MessageSelector a -> MessageSelector a -> MessageSelector a

sconcat :: NonEmpty (MessageSelector a) -> MessageSelector a

stimes :: Integral b => b -> MessageSelector a -> MessageSelector a

Semigroup a => Monoid (MessageSelector a)

Defined in Control.Eff.Concurrent.Process

Methods

mempty :: MessageSelector a

mappend :: MessageSelector a -> MessageSelector a -> MessageSelector a

mconcat :: [MessageSelector a] -> MessageSelector a

selectMessage :: (NFData t, Typeable t) => MessageSelector t

Create a message selector for a value that can be obtained by fromDynamic. It will also force the result.

Since: 0.9.1

selectMessageLazy :: Typeable t => MessageSelector t

Create a message selector for a value that can be obtained by fromDynamic. It will also force the result.

Since: 0.9.1

selectMessageProxy :: forall proxy t. (NFData t, Typeable t) => proxy t -> MessageSelector t

Create a message selector for a value that can be obtained by fromDynamic with a proxy argument. It will also force the result.

Since: 0.9.1

selectMessageProxyLazy :: forall proxy t. Typeable t => proxy t -> MessageSelector t

Create a message selector for a value that can be obtained by fromDynamic with a proxy argument. It will also force the result.

Since: 0.9.1

filterMessage :: (Typeable a, NFData a) => (a -> Bool) -> MessageSelector a

Create a message selector from a predicate. It will force the result.

Since: 0.9.1

filterMessageLazy :: Typeable a => (a -> Bool) -> MessageSelector a

Create a message selector from a predicate. It will force the result.

Since: 0.9.1

selectMessageWith :: (Typeable a, NFData b) => (a -> Maybe b) -> MessageSelector b

Select a message of type a and apply the given function to it. If the function returns Just The ReceiveSelectedMessage function will return the result (sans Maybe). It will force the result.

Since: 0.9.1

selectMessageWithLazy :: Typeable a => (a -> Maybe b) -> MessageSelector b

Select a message of type a and apply the given function to it. If the function returns Just The ReceiveSelectedMessage function will return the result (sans Maybe). It will force the result.

Since: 0.9.1

selectDynamicMessage :: NFData a => (Dynamic -> Maybe a) -> MessageSelector a

Create a message selector. It will force the result.

Since: 0.9.1

selectDynamicMessageLazy :: (Dynamic -> Maybe a) -> MessageSelector a

Create a message selector.

Since: 0.9.1

selectAnyMessageLazy :: MessageSelector Dynamic

Create a message selector that will match every message. This is lazy because the result is not forceed.

Since: 0.9.1

Process Life Cycle Management

self :: (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> Eff r ProcessId

Returns the ProcessId of the current process.

isProcessAlive :: forall r q. (HasCallStack, SetMember Process (Process q) r, Member Interrupts r) => SchedulerProxy q -> ProcessId -> Eff r Bool

Return True if the process is alive.

Since: 0.12.0

Spawning

spawn :: forall r q. (HasCallStack, SetMember Process (Process q) r, Member Interrupts r) => Eff (InterruptableProcess q) () -> Eff r ProcessId

Start a new process, the new process will execute an effect, the function will return immediately with a ProcessId. If the new process is interrupted, the process will Shutdown with the InterruptReason wrapped in NotCovered. For specific use cases it might be better to use spawnRaw.

spawn_ :: forall r q. (HasCallStack, SetMember Process (Process q) r, Member Interrupts r) => Eff (InterruptableProcess q) () -> Eff r ()

Like spawn but return ().

spawnLink :: forall r q. (HasCallStack, SetMember Process (Process q) r, Member Interrupts r) => Eff (InterruptableProcess q) () -> Eff r ProcessId

Start a new process, and immediately link to it.

Since: 0.12.0

spawnRaw :: forall r q. (HasCallStack, SetMember Process (Process q) r, Member Interrupts r) => Eff (ConsProcess q) () -> Eff r ProcessId

Start a new process, the new process will execute an effect, the function will return immediately with a ProcessId. The spawned process has only the raw ConsProcess effects. For non-library code spawn might be better suited.

spawnRaw_ :: forall r q. (HasCallStack, SetMember Process (Process q) r, Member Interrupts r) => Eff (ConsProcess q) () -> Eff r ()

Like spawnRaw but return ().

Process Exit or Interrupt

exitBecause :: forall r q a. (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> ExitReason NoRecovery -> Eff r a

Exit the process with a ProcessExitReaon.

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

Exit the process.

exitWithError :: forall r q a. (HasCallStack, SetMember Process (Process q) r) => SchedulerProxy q -> String -> Eff r a

Exit the process with an error.

Links

linkProcess :: forall r q. (HasCallStack, SetMember Process (Process q) r, Member Interrupts r) => SchedulerProxy q -> ProcessId -> Eff r ()

Connect the calling process to another process, such that if one of the processes crashes (i.e. isCrash returns True), the other is shutdown with the ProcessExitReaon LinkedProcessCrashed.

Since: 0.12.0

unlinkProcess :: forall r q. (HasCallStack, SetMember Process (Process q) r, Member Interrupts r) => SchedulerProxy q -> ProcessId -> Eff r ()

Unlink the calling proccess from the other process.

Since: 0.12.0

Monitors

monitor :: forall r q. (HasCallStack, SetMember Process (Process q) r, Member Interrupts r) => SchedulerProxy q -> ProcessId -> Eff r MonitorReference

Monitor another process. When the monitored process exits a ProcessDown is sent to the calling process. The return value is a unique identifier for that monitor. There can be multiple monitors on the same process, and a message for each will be sent. If the process is already dead, the ProcessDown message will be sent immediately, w.thout exit reason

Since: 0.12.0

demonitor :: forall r q. (HasCallStack, SetMember Process (Process q) r, Member Interrupts r) => SchedulerProxy q -> MonitorReference -> Eff r ()

Remove a monitor created with monitor.

Since: 0.12.0

data ProcessDown

A monitored process exited. This message is sent to a process by the scheduler, when a process that was monitored via a SchedulerCommand died.

Since: 0.12.0

Constructors

ProcessDown

Fields

• downReference :: !MonitorReference
• downReason :: !SomeExitReason

Instances

Eq ProcessDown

Defined in Control.Eff.Concurrent.Process

Methods

(==) :: ProcessDown -> ProcessDown -> Bool

(/=) :: ProcessDown -> ProcessDown -> Bool

Ord ProcessDown

Defined in Control.Eff.Concurrent.Process

Methods

compare :: ProcessDown -> ProcessDown -> Ordering

(<) :: ProcessDown -> ProcessDown -> Bool

(<=) :: ProcessDown -> ProcessDown -> Bool

(>) :: ProcessDown -> ProcessDown -> Bool

(>=) :: ProcessDown -> ProcessDown -> Bool

max :: ProcessDown -> ProcessDown -> ProcessDown

min :: ProcessDown -> ProcessDown -> ProcessDown

Show ProcessDown

Defined in Control.Eff.Concurrent.Process

Methods

showsPrec :: Int -> ProcessDown -> ShowS

show :: ProcessDown -> String

showList :: [ProcessDown] -> ShowS

Generic ProcessDown

Defined in Control.Eff.Concurrent.Process

Associated Types

type Rep ProcessDown :: Type -> Type

Methods

from :: ProcessDown -> Rep ProcessDown x

to :: Rep ProcessDown x -> ProcessDown

NFData ProcessDown

Defined in Control.Eff.Concurrent.Process

Methods

rnf :: ProcessDown -> ()

type Rep ProcessDown

Defined in Control.Eff.Concurrent.Process

type Rep ProcessDown = D1 (MetaData "ProcessDown" "Control.Eff.Concurrent.Process" "extensible-effects-concurrent-0.14.0-KhFRpYG1b4SDYIjm4HuI8R" False) (C1 (MetaCons "ProcessDown" PrefixI True) (S1 (MetaSel (Just "downReference") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 MonitorReference) :*: S1 (MetaSel (Just "downReason") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 SomeExitReason)))

selectProcessDown :: MonitorReference -> MessageSelector ProcessDown

A MesssageSelector for the ProcessDown message of a specific process.

Since: 0.12.0

becauseProcessIsDown :: ProcessDown -> InterruptReason

Trigger an Interrupt for a ProcessDown message. The reason will be ProcessNotRunning

Since: 0.12.0

data MonitorReference

A value that contains a unique reference of a process monitoring.

Since: 0.12.0

Constructors

MonitorReference

Fields

• monitorIndex :: Int
• monitoredProcess :: ProcessId

Instances

Eq MonitorReference

Defined in Control.Eff.Concurrent.Process

Methods

(==) :: MonitorReference -> MonitorReference -> Bool

(/=) :: MonitorReference -> MonitorReference -> Bool

Ord MonitorReference

Defined in Control.Eff.Concurrent.Process

Methods

compare :: MonitorReference -> MonitorReference -> Ordering

(<) :: MonitorReference -> MonitorReference -> Bool

(<=) :: MonitorReference -> MonitorReference -> Bool

(>) :: MonitorReference -> MonitorReference -> Bool

(>=) :: MonitorReference -> MonitorReference -> Bool

max :: MonitorReference -> MonitorReference -> MonitorReference

min :: MonitorReference -> MonitorReference -> MonitorReference

Read MonitorReference

Defined in Control.Eff.Concurrent.Process

Methods

readsPrec :: Int -> ReadS MonitorReference

readList :: ReadS [MonitorReference]

readPrec :: ReadPrec MonitorReference

readListPrec :: ReadPrec [MonitorReference]

Show MonitorReference

Defined in Control.Eff.Concurrent.Process

Methods

showsPrec :: Int -> MonitorReference -> ShowS

show :: MonitorReference -> String

showList :: [MonitorReference] -> ShowS

Generic MonitorReference

Defined in Control.Eff.Concurrent.Process

Associated Types

type Rep MonitorReference :: Type -> Type

Methods

from :: MonitorReference -> Rep MonitorReference x

to :: Rep MonitorReference x -> MonitorReference

NFData MonitorReference

Defined in Control.Eff.Concurrent.Process

Methods

rnf :: MonitorReference -> ()

type Rep MonitorReference

Defined in Control.Eff.Concurrent.Process

type Rep MonitorReference = D1 (MetaData "MonitorReference" "Control.Eff.Concurrent.Process" "extensible-effects-concurrent-0.14.0-KhFRpYG1b4SDYIjm4HuI8R" False) (C1 (MetaCons "MonitorReference" PrefixI True) (S1 (MetaSel (Just "monitorIndex") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Int) :*: S1 (MetaSel (Just "monitoredProcess") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ProcessId)))

withMonitor :: (HasCallStack, Member Interrupts r, SetMember Process (Process q) r, Member Interrupts r) => SchedulerProxy q -> ProcessId -> (MonitorReference -> Eff r a) -> Eff r a

monitor another process before while performing an action and demonitor afterwards.

Since: 0.12.0

receiveWithMonitor :: (HasCallStack, Member Interrupts r, SetMember Process (Process q) r, Member Interrupts r, Typeable a, Show a) => SchedulerProxy q -> ProcessId -> MessageSelector a -> Eff r (Either ProcessDown a)

A MessageSelector for receiving either a monitor of the given process or another message.

Since: 0.12.0

Process Interrupt Handling

provideInterruptsShutdown :: forall e a. Eff (InterruptableProcess e) a -> Eff (ConsProcess e) a

Handle all InterruptReasons of an InterruptableProcess by wrapping them up in NotRecovered and then do a process Shutdown.

handleInterrupts :: (HasCallStack, Member Interrupts r) => (InterruptReason -> Eff r a) -> Eff r a -> Eff r a

Handle InterruptReasons arising during process operations, e.g. when a linked process crashes while we wait in a receiveSelectedMessage via a call to interrupt.

tryUninterrupted :: (HasCallStack, Member Interrupts r) => Eff r a -> Eff r (Either InterruptReason a)

Like handleInterrupts, but instead of passing the InterruptReason to a handler function, Either is returned.

Since: 0.13.2

exitOnInterrupt :: (HasCallStack, Member Interrupts r, SetMember Process (Process q) r) => SchedulerProxy q -> Eff r a -> Eff r a

Handle InterruptReasons arising during process operations, e.g. when a linked process crashes while we wait in a receiveSelectedMessage via a call to interrupt.

logInterrupts :: (HasCallStack, '[Interrupts, Logs LogMessage] <:: r) => Eff r () -> Eff r ()

Handle interrupts by logging them with logProcessExit and otherwise ignoring them.

provideInterrupts :: HasCallStack => Eff (Interrupts ': r) a -> Eff r (Either InterruptReason a)

Handle InterruptReasons arising during process operations, e.g. when a linked process crashes while we wait in a receiveSelectedMessage via a call to interrupt.

mergeEitherInterruptAndExitReason :: Either InterruptReason (ExitReason NoRecovery) -> ExitReason NoRecovery

Wrap all (left) InterruptReasons into NotRecovered and return the (right) NoRecovery ExitReasons as is.

interrupt :: (HasCallStack, Member Interrupts r) => InterruptReason -> Eff r a

Throw an InterruptReason, can be handled by recoverFromInterrupt or exitOnInterrupt or provideInterrupts.

Process Operation Execution

executeAndResume :: forall q r v. (SetMember Process (Process q) r, HasCallStack) => Process q (ResumeProcess v) -> Eff r (Either (ExitReason Recoverable) v)

Execute a and action and return the result; if the process is interrupted by an error or exception, or an explicit shutdown from another process, or through a crash of a linked process, i.e. whenever the exit reason satisfies isRecoverable, return the exit reason.

executeAndResumeOrExit :: forall r q v. (SetMember Process (Process q) r, HasCallStack) => Process q (ResumeProcess v) -> Eff r v

Execute a Process action and resume the process, exit the process when an Interrupts was raised. Use executeAndResume to catch interrupts.

executeAndResumeOrThrow :: forall q r v. (SetMember Process (Process q) r, HasCallStack, Member Interrupts r) => Process q (ResumeProcess v) -> Eff r v

Execute a Process action and resume the process, exit the process when an Interrupts was raised. Use executeAndResume to catch interrupts.

Exit Or Interrupt Reasons

data ExitReason (t :: ExitRecovery) where

A sum-type with reasons for why a process exists the scheduling loop, this includes errors, that can occur when scheduleing messages.

Constructors

ProcessFinished :: ExitReason Recoverable

A process has finished a unit of work and might exit or work on something else. This is primarily used for interupting infinite server loops, allowing for additional cleanup work before exitting (e.g. with ExitNormally)

Since: 0.13.2

ProcessNotRunning :: ProcessId -> ExitReason Recoverable

A process that should be running was not running.

LinkedProcessCrashed :: ProcessId -> ExitReason Recoverable

A linked process is down

ProcessError :: String -> ExitReason Recoverable

An exit reason that has an error message but isn't Recoverable.

ExitNormally :: ExitReason NoRecovery

A process function returned or exited without any error.

NotRecovered :: ExitReason Recoverable -> ExitReason NoRecovery

An unhandled Recoverable allows NoRecovery.

UnexpectedException :: String -> String -> ExitReason NoRecovery

An unexpected runtime exception was thrown, i.e. an exception derived from SomeException

Killed :: ExitReason NoRecovery

A process was cancelled (e.g. killed, in cancel)

Instances

Eq (ExitReason x)

Defined in Control.Eff.Concurrent.Process

Methods

(==) :: ExitReason x -> ExitReason x -> Bool

(/=) :: ExitReason x -> ExitReason x -> Bool

Ord (ExitReason x)

Defined in Control.Eff.Concurrent.Process

Methods

compare :: ExitReason x -> ExitReason x -> Ordering

(<) :: ExitReason x -> ExitReason x -> Bool

(<=) :: ExitReason x -> ExitReason x -> Bool

(>) :: ExitReason x -> ExitReason x -> Bool

(>=) :: ExitReason x -> ExitReason x -> Bool

max :: ExitReason x -> ExitReason x -> ExitReason x

min :: ExitReason x -> ExitReason x -> ExitReason x

Show (ExitReason x)

Defined in Control.Eff.Concurrent.Process

Methods

showsPrec :: Int -> ExitReason x -> ShowS

show :: ExitReason x -> String

showList :: [ExitReason x] -> ShowS

Exception (ExitReason Recoverable)

Defined in Control.Eff.Concurrent.Process

Methods

toException :: ExitReason Recoverable -> SomeException

fromException :: SomeException -> Maybe (ExitReason Recoverable)

displayException :: ExitReason Recoverable -> String

Exception (ExitReason NoRecovery)

Defined in Control.Eff.Concurrent.Process

Methods

toException :: ExitReason NoRecovery -> SomeException

fromException :: SomeException -> Maybe (ExitReason NoRecovery)

displayException :: ExitReason NoRecovery -> String

NFData (ExitReason x)

Defined in Control.Eff.Concurrent.Process

Methods

rnf :: ExitReason x -> ()

data ExitRecovery

This kind is used to indicate if a ExitReason can be treated like a short interrupt which can be handled or ignored.

Constructors

Recoverable

NoRecovery

Instances

Eq ExitRecovery

Defined in Control.Eff.Concurrent.Process

Methods

(==) :: ExitRecovery -> ExitRecovery -> Bool

(/=) :: ExitRecovery -> ExitRecovery -> Bool

Ord ExitRecovery

Defined in Control.Eff.Concurrent.Process

Methods

compare :: ExitRecovery -> ExitRecovery -> Ordering

(<) :: ExitRecovery -> ExitRecovery -> Bool

(<=) :: ExitRecovery -> ExitRecovery -> Bool

(>) :: ExitRecovery -> ExitRecovery -> Bool

(>=) :: ExitRecovery -> ExitRecovery -> Bool

max :: ExitRecovery -> ExitRecovery -> ExitRecovery

min :: ExitRecovery -> ExitRecovery -> ExitRecovery

Show ExitRecovery

Defined in Control.Eff.Concurrent.Process

Methods

showsPrec :: Int -> ExitRecovery -> ShowS

show :: ExitRecovery -> String

showList :: [ExitRecovery] -> ShowS

Generic ExitRecovery

Defined in Control.Eff.Concurrent.Process

Associated Types

type Rep ExitRecovery :: Type -> Type

Methods

from :: ExitRecovery -> Rep ExitRecovery x

to :: Rep ExitRecovery x -> ExitRecovery

NFData ExitRecovery

Defined in Control.Eff.Concurrent.Process

Methods

rnf :: ExitRecovery -> ()

type Rep ExitRecovery

Defined in Control.Eff.Concurrent.Process

type Rep ExitRecovery = D1 (MetaData "ExitRecovery" "Control.Eff.Concurrent.Process" "extensible-effects-concurrent-0.14.0-KhFRpYG1b4SDYIjm4HuI8R" False) (C1 (MetaCons "Recoverable" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "NoRecovery" PrefixI False) (U1 :: Type -> Type))

type InterruptReason = ExitReason Recoverable

ExitReasons which are recoverable are interrupts.

type Interrupts = Exc InterruptReason

Exceptions containing InterruptReasons. See handleInterrupts, exitOnInterrupt or provideInterrupts

type InterruptableProcess e = Interrupts ': ConsProcess e

This adds a layer of the Interrupts effect ontop of ConsProcess

data ExitSeverity

This value indicates wether a process exited in way consistent with the planned behaviour or not.

Constructors

NormalExit

Crash

Instances

Eq ExitSeverity

Defined in Control.Eff.Concurrent.Process

Methods

(==) :: ExitSeverity -> ExitSeverity -> Bool

(/=) :: ExitSeverity -> ExitSeverity -> Bool

Ord ExitSeverity

Defined in Control.Eff.Concurrent.Process

Methods

compare :: ExitSeverity -> ExitSeverity -> Ordering

(<) :: ExitSeverity -> ExitSeverity -> Bool

(<=) :: ExitSeverity -> ExitSeverity -> Bool

(>) :: ExitSeverity -> ExitSeverity -> Bool

(>=) :: ExitSeverity -> ExitSeverity -> Bool

max :: ExitSeverity -> ExitSeverity -> ExitSeverity

min :: ExitSeverity -> ExitSeverity -> ExitSeverity

Show ExitSeverity

Defined in Control.Eff.Concurrent.Process

Methods

showsPrec :: Int -> ExitSeverity -> ShowS

show :: ExitSeverity -> String

showList :: [ExitSeverity] -> ShowS

Generic ExitSeverity

Defined in Control.Eff.Concurrent.Process

Associated Types

type Rep ExitSeverity :: Type -> Type

Methods

from :: ExitSeverity -> Rep ExitSeverity x

to :: Rep ExitSeverity x -> ExitSeverity

NFData ExitSeverity

Defined in Control.Eff.Concurrent.Process

Methods

rnf :: ExitSeverity -> ()

type Rep ExitSeverity

Defined in Control.Eff.Concurrent.Process

type Rep ExitSeverity = D1 (MetaData "ExitSeverity" "Control.Eff.Concurrent.Process" "extensible-effects-concurrent-0.14.0-KhFRpYG1b4SDYIjm4HuI8R" False) (C1 (MetaCons "NormalExit" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Crash" PrefixI False) (U1 :: Type -> Type))

data SomeExitReason where

An existential wrapper around ExitReason

Constructors

SomeExitReason :: ExitReason x -> SomeExitReason

Instances

Eq SomeExitReason

Defined in Control.Eff.Concurrent.Process

Methods

(==) :: SomeExitReason -> SomeExitReason -> Bool

(/=) :: SomeExitReason -> SomeExitReason -> Bool

Ord SomeExitReason

Defined in Control.Eff.Concurrent.Process

Methods

compare :: SomeExitReason -> SomeExitReason -> Ordering

(<) :: SomeExitReason -> SomeExitReason -> Bool

(<=) :: SomeExitReason -> SomeExitReason -> Bool

(>) :: SomeExitReason -> SomeExitReason -> Bool

(>=) :: SomeExitReason -> SomeExitReason -> Bool

max :: SomeExitReason -> SomeExitReason -> SomeExitReason

min :: SomeExitReason -> SomeExitReason -> SomeExitReason

Show SomeExitReason

Defined in Control.Eff.Concurrent.Process

Methods

showsPrec :: Int -> SomeExitReason -> ShowS

show :: SomeExitReason -> String

showList :: [SomeExitReason] -> ShowS

NFData SomeExitReason

Defined in Control.Eff.Concurrent.Process

Methods

rnf :: SomeExitReason -> ()

toExitRecovery :: ExitReason r -> ExitRecovery

Get the ExitRecovery

isRecoverable :: ExitReason x -> Bool

A predicate for recoverable exit reasons. This predicate defines the exit reasonson which functions such as executeAndResume

toExitSeverity :: ExitReason e -> ExitSeverity

Get the ExitSeverity of a ExitReason.

isBecauseDown :: Maybe ProcessId -> ExitReason r -> Bool

A predicate for linked process crashes.

isCrash :: ExitReason x -> Bool

A predicate for crashes. A crash happens when a process exits with an ExitReason other than ExitNormally

toCrashReason :: ExitReason x -> Maybe String

Print a ExitReason to Just a formatted String when isCrash is True. This can be useful in combination with view patterns, e.g.:

logCrash :: ExitReason -> Eff e ()
logCrash (toCrashReason -> Just reason) = logError reason
logCrash _ = return ()

Though this can be improved to:

logCrash = traverse_ logError . toCrashReason

fromSomeExitReason :: SomeExitReason -> Either (ExitReason NoRecovery) InterruptReason

Partition a SomeExitReason back into either a NoRecovery or a Recoverable ExitReason

logProcessExit :: (HasCallStack, Member (Logs LogMessage) e) => ExitReason x -> Eff e ()

Log the ProcessExitReaons