NgxExport.Tools.Combinators

Combinators of effectful actions

A set of functions to combine effectful actions for building handlers and services tuned for special purposes.

Exported functions

voidHandler

Arguments

:: IO a

Target computation

-> IO ByteString

Runs an effectful computation and then returns an empty ByteString.

This function saves printing the final return L.empty action in handlers that return unused or empty ByteString.

For example, service signalUpconf being used as an update callback in

type Upconf = [Text]

signalUpconf :: Upconf -> NgxExportService
signalUpconf upconf = const $ do
    mapConcurrently_ getUrl upconf
    return L.empty

ngxExportSimpleServiceTyped 'signalUpconf ''Upconf $
    PersistentService Nothing

returns an empty bytestring which is not used in a meaningful way, therefore it can be rewritten as

signalUpconf :: Upconf -> NgxExportService
signalUpconf = const . voidHandler . mapConcurrently_ getUrl

which helps to focus better on the computation itself.

Since: 1.2.0

voidHandler'

Arguments

:: IO a

Target computation

-> b

Ignored value

-> IO ByteString

Runs an effectful computation and then returns an empty ByteString.

The same as voidHandler except it accepts an additional value which is ignored. Implemented as

voidHandler' = const . voidHandler

This can be useful in declarations of services that accept a boolean flag which marks whether the service is running for the first time. This flag is often ignored though, in which case using voidHandler' can simplify code.

For instance, service signalUpconf from the example for voidHandler can be further simplified as

signalUpconf :: Upconf -> NgxExportService
signalUpconf = voidHandler' . mapConcurrently_ getUrl

Since: 1.2.1

voidService

Arguments

:: a

Ignored configuration

-> Bool

Ignored boolean value

-> IO ByteString

A void service which does nothing and returns an empty ByteString.

The service is implemented as a split service in terms of module NgxExport.Tools.SplitService. On the first iteration the service returns immediately, on the next iteration it sleeps until the worker process terminates it during the shutdown.

This can be used for loading global data from the Nginx configuration in a more concise and declarative way.

For example, if data Conf in

newtype Conf = Conf Int deriving (Read, Show)

testLoadConf :: Conf -> NgxExportService
testLoadConf = voidService

ngxExportSimpleServiceTyped 'testLoadConf ''Conf restartPromptly

gets loaded by service testLoadConf from the Nginx configuration, then it can be accessed in the Haskell code via IORef data storage storage_Conf_testLoadConf.

Declaration of restartPromptly establishes a persistent service mode without delay. The short iteration at the start of the service can be used for calling a service update hook.

Note that voidService is still an asynchronous service which means that the global data it loads may appear uninitialized in very early client requests. To ensure that the data gets loaded before processing client requests, consider using the synchronous initialization hook ngxExportInitHook as a distinct solution or in conjunction with other services.

Since: 1.2.3

rareService :: ServiceMode

A persistent service which waits for 24 hours before restart.

This declaration had been recommended for using with voidService until the latter was reimplemented as a split service. Nevertheless, it still can be used for this purpose.

Since: 1.2.5

restartPromptly :: ServiceMode

A persistent service which restarts without delay.

This convenient declaration can be used for loading global data from the Nginx configuration with voidService.

Since: 1.2.6

Split services

module NgxExport.Tools.SplitService