Control.Monad.Component.Internal.Core

Documentation

buildComponent

Arguments

:: Text

Unique name for the component being allocated

-> IO a

Allocation IO sub-routine

-> (a -> IO ())

Cleanup IO sub-routine

-> ComponentM a

Use this function when you want to allocate a new resource (e.g. Database, Socket, etc). It registers the constructed resource in your application component tree and guarantees that its cleanup sub-routine is executed at the end of your program.

This function is similar to the bracket function with the caveat that it expects a Text argument which identifies the component being allocated.

NOTE: The name of your component must be unique; otherwise a DuplicatedComponentKeyDetected will be thrown

buildComponent_ :: Text -> IO a -> ComponentM a

Transforms an IO sub-routine into a ComponentM sub-routine; the given IO sub-routine returns a resource that does not allocate any other resources that would need to be cleaned up on a system shutdown.

This is similar to using liftIO, with the caveat that the library will register the given IO sub-routine as a Component, and it will keep track and report its initialization timespan

runComponentM

Arguments

:: Text

Name of your application (used for tracing purposes)

-> ComponentM a

Builder of your application environment

-> (a -> IO b)

Function where your main application will live

-> IO b

Constructs the environment of your application by executing the IO sub-routines provided in the buildComponent and buildComponent_ functions; it then executes a callback where your main application will run.

This function:

• Keeps track of initialization elapsed time for each component of your application
• Initializes components concurrently as long as they are composed using Applicative functions
• Builds a graph of your dependencies automatically when composing your ComponentM values via Applicative or Monad interfaces; it then guarantees the execution of cleanup operations in a topological sorted order
• Guarantees the proper cleanup of previously allocated resources if the creation of a resource throws an exception on initialization
• Guarantees best-effort cleanup of resources on application teardown in the scenario where a cleanup sub-routine throws an exception
• Keeps track of teardown elasped time for each component of your application; and reports what exceptions was thrown in case of failures

If you want to trace the behavior of your application on initialization and teardown, use runComponentM1 instead

runComponentM1

Arguments

:: (ComponentEvent -> IO ())

Callback function to trace ComponentEvent records

-> Text

Name of your application (used for tracing purposes)

-> ComponentM a

Builder of your application environment

-> (a -> IO b)

Function where your main application will live

-> IO b

Enhances runComponentM with a callback function that emits ComponentEvent records. These events are a great way of tracing the lifecycle and structure of your application.