Copyright | (c) Naoto Shimazaki 2017 |
---|---|
License | MIT (see the file LICENSE) |
Maintainer | https://github.com/nshimaza |
Stability | experimental |
Safe Haskell | Safe |
Language | Haskell2010 |
Managing Haskell threads in hierarchical manner.
Threads created by newChild guarantee automatic cleanup on its exit regardless normal exit or cancellation by asynchronous exception.
In order to this module works properly, user must ensure following rules.
- User provided thread handler must accept
ThreadMap
as its first argument. - When new thread created by newChild, handler receives newly created empty
ThreadMap
. - When the user provided handler creates its child thread, it must use newChild.
- At the same time, the handler must pass the
ThreadMap
received via its argument to newChild.
ThreadMap
is mutable map holding live threads. Each threads managed by this module has its
own ThreadMap
instance. Each ThreadMap
keeps live "child" threads for future cleanup on exit.
Populating ThreadMap
is done by newChild automatically.
Actually the function newChild accept a ThreadMap
then mutate it.
At the same time newChild create a new empty ThreadMap
for newly created thread and pass it
to user provided handler of the new thread.
Also newChild automatically install cleanup routine which kill all threads living in the new
ThreadMap
created for the thread.
The cleanup routine also unregister itself from ThreadMap
of parent.
In order to work this properly, user provided thread handler must use newChild with ThreadMap
given via its argument when it creates its child so that cleanup routine can terminate
its children properly.
Example
When you create the first thread managed by this module, create a new empty ThreadMap
then call
newChild with it. The newCall automatically install cleanup routine to the handler you provided.
createRootThread :: IO ThreadId createRootThread = do rootThreadMap <- newThreadMap threadID <- newChild rootThreadMap rootThreadHandler return threadID
When a thread managed by this module creates its child thread, call newChild with TreadMap
received via handlers argument.
rootThreadHandler :: ThreadMap -> IO () rootThreadHandler myChildrenThreadMap = do void $ newChild myChildrenThreadMap $ grandChildrenThreadMap -> do yourCode return ()
You can install your own cleanup routine using finally or both resource acquisition and cleanup routine using bracket.
-- Forking a new child with your own cleanup void $ newChild childrenOfCurrentThread $ childrenOfHandler -> yourThreadHandler `finally` yourCleanupRoutine -- Forking a new child with resource acquisition and cleanup void $ newChild childrenOfCurrentThread $ childrenOfHandler -> bracket yourResourceAcquiringRoutine yourCleanupRoutine yourThreadHandler
Limitation
Currently, unlike async function, this module is not designed to back any return value from child thread to parent thread. This module focuses on guaranteed cleanup on thread termination.
- data FinishMarker
- data ThreadMap
- newThreadMap :: IO ThreadMap
- newChild :: ThreadMap -> (ThreadMap -> IO ()) -> IO ThreadId
- killThreadHierarchy :: ThreadMap -> IO ()
Types
data FinishMarker Source #
FinishMarker is created as empty MVar when a thread is created. It is automatically filled by () when the thread exits.