diff --git a/Changelog.md b/Changelog.md --- a/Changelog.md +++ b/Changelog.md @@ -1,3 +1,11 @@ +### 0.4.0.0 + +- Now services with *SingleShotService* strategy run exactly two times during + the lifetime of a worker process: this lets using them in initialization / + cleanup flow. Accordingly, the *first-run* flag is passed to them again. +- Added a number of combinators to facilitate creation of specialized services. + They allow distinguishing between *ignition* and *deferred* services. + ### 0.3.3.0 - In case of unreadable configuration, terminate the worker process by throwing diff --git a/NgxExport/Tools.hs b/NgxExport/Tools.hs --- a/NgxExport/Tools.hs +++ b/NgxExport/Tools.hs @@ -1,5 +1,6 @@ {-# LANGUAGE TemplateHaskell, ForeignFunctionInterface, TypeFamilies #-} -{-# LANGUAGE EmptyDataDecls, DeriveGeneric, DeriveLift, NumDecimals #-} +{-# LANGUAGE EmptyDataDecls, DeriveGeneric, DeriveLift #-} +{-# LANGUAGE LambdaCase, NumDecimals #-} ----------------------------------------------------------------------------- -- | @@ -39,6 +40,11 @@ ,ngxExportSimpleService ,ngxExportSimpleServiceTyped ,ngxExportSimpleServiceTypedAsJSON + -- * Split services + -- $splitServices + ,splitService + ,ignitionService + ,deferredService -- * Re-exported data constructors from /Foreign.C/ -- | Re-exports are needed by exporters for marshalling in foreign calls. ,Foreign.C.Types.CInt (..) @@ -394,8 +400,8 @@ -- | ConfJSONCon2 deriving (Generic, Show) -- instance FromJSON ConfJSON -- --- testReadConfJSON :: ConfJSON -> IO L.ByteString --- __/testReadConfJSON/__ = testRead +-- testReadConfJSON :: ConfJSON -> Bool -> IO L.ByteString +-- __/testReadConfJSON/__ = 'ignitionService' testRead -- 'ngxExportSimpleServiceTypedAsJSON' \'testReadConfJSON \'\'ConfJSON -- 'SingleShotService' -- @ @@ -417,11 +423,15 @@ -- * /Single-shot/ services (@'SingleShotService'@) -- -- In this toy example the most efficient sleeping strategy is a single-shot --- service because data is not altered during runtime. Under the hood, the --- single-shot strategy is implemented as periodical sleeps (with period of --- @'Hr' 1@), except it runs the handler only on the first iteration, while --- afterwards it merely returns empty values: as such, this strategy should be --- accompanied by Nginx directive __/haskell_service_var_ignore_empty/__. +-- service because data is not altered during runtime. A single-shot service +-- runs exactly two times during the lifetime of a worker process: the first +-- run (when the second argument of the service, i.e. the /first-run/ flag, is +-- /True/) is immediately followed by the second run (when the the /first-run/ +-- flag is /False/). On the second run the service handler is used as an +-- exception handler when the service is shutting down after the 'ThreadKilled' +-- exception thrown. Accordingly, a single-shot handler can be used for +-- allocation of some global resources (when the first-run flag is /True/), and +-- cleaning them up (when the first-run flag is /False/). -- -- Notice that service /testReadConfWithDelay/ manages time delays on its own, -- therefore it uses /no-sleeps/ strategy @'PersistentService' Nothing@. @@ -462,8 +472,6 @@ -- $hs_testReadConfJSON -- \'{\"tag\":\"ConfJSONCon1\", \"contents\":56}\'; -- --- haskell_service_var_ignore_empty $hs_testReadConfJSON; --- -- server { -- listen 8010; -- server_name main; @@ -502,9 +510,6 @@ -- > hs_testConfStorage: Just (Conf 20) -- | Defines a sleeping strategy. --- --- Single-shot services should be accompanied by Nginx directive --- __/haskell_service_var_ignore_empty/__. data ServiceMode -- | Persistent service (with or without periodical sleeps) = PersistentService (Maybe TimeInterval) @@ -566,11 +571,17 @@ |] ) SingleShotService -> - ([|unless $(eFstRun) $ - threadDelaySec $ toSec $ Hr 1|] + ([|unless $(eFstRun) $ handle + (\case + ThreadKilled -> do + conf_data__ <- $(initConf) + void $ $(eF) (fromJust conf_data__) False + _ -> return () + ) $ forever $ threadDelaySec $ toSec $ Hr 24 + |] ,[|\conf_data__ -> if $(eFstRun) - then $(eF) $ fromJust conf_data__ + then $(eF) (fromJust conf_data__) True else return L.empty |] ) @@ -607,12 +618,6 @@ -- 'ByteString' -> 'Prelude.Bool' -> 'IO' 'L.ByteString' -- @ -- --- or (when service mode is 'SingleShotService') --- --- @ --- 'ByteString' -> 'IO' 'L.ByteString' --- @ --- -- with specified name and service mode. ngxExportSimpleService :: Name -- ^ Name of the service -> ServiceMode -- ^ Service mode @@ -626,12 +631,6 @@ -- 'Read' a => a -> 'Prelude.Bool' -> 'IO' 'L.ByteString' -- @ -- --- or (when service mode is 'SingleShotService') --- --- @ --- 'Read' a => a -> 'IO' 'L.ByteString' --- @ --- -- with specified name and service mode. -- -- The service expects an object of a custom type deriving 'Read' as its @@ -658,12 +657,6 @@ -- 'FromJSON' a => a -> 'Prelude.Bool' -> 'IO' 'L.ByteString' -- @ -- --- or (when service mode is 'SingleShotService') --- --- @ --- 'FromJSON' a => a -> 'IO' 'L.ByteString' --- @ --- -- with specified name and service mode. -- -- The service expects an object of a custom type deriving 'FromJSON' as its @@ -683,4 +676,49 @@ -> Q [Dec] ngxExportSimpleServiceTypedAsJSON f c = ngxExportSimpleService' f $ Just (c, True) + +-- $splitServices +-- +-- Here are a number of combinators to facilitate creation of specialized +-- services. They allow distinguishing between /ignition/ and /deferred/ +-- services: the former run when the /first-run/ flag is /True/ whereas the +-- latter run when the flag is /False/. The most promising use case for these +-- helper functions is tuning of /single-shot/ services: in this case the +-- ignition service corresponds to a normal single-shot action on startup of a +-- worker process, while the deferred service corresponds to a cleanup handler +-- and runs when a worker process exits. +-- +-- In all helpers, configuration and the first-run flag parameters belong to +-- the common service signature, and therefore should not be bound by any +-- arguments. + +-- | Sets two different actions as ignition and deferred services. +-- +-- When used as a single-shot service, the second action only runs on exit of a +-- worker process, and therefore can be used as a cleanup handler. +splitService :: (a -> IO L.ByteString) -- ^ Ignition service + -> (a -> IO L.ByteString) -- ^ Deferred service + -> a -- ^ Configuration + -> Bool -- ^ First-run flag + -> IO L.ByteString +splitService is ds c fstRun + | fstRun = is c + | otherwise = ds c + +-- | Sets an action as an ignition service. +ignitionService :: (a -> IO L.ByteString) -- ^ Ignition service + -> a -- ^ Configuration + -> Bool -- ^ First-run flag + -> IO L.ByteString +ignitionService is = splitService is $ const $ return L.empty + +-- | Sets an action as a deferred service. +-- +-- When used as a single-shot service, the action only runs on exit of a worker +-- process, and therefore can be used as a cleanup handler. +deferredService :: (a -> IO L.ByteString) -- ^ Deferred service + -> a -- ^ Configuration + -> Bool -- ^ First-run flag + -> IO L.ByteString +deferredService = splitService $ const $ return L.empty diff --git a/ngx-export-tools.cabal b/ngx-export-tools.cabal --- a/ngx-export-tools.cabal +++ b/ngx-export-tools.cabal @@ -1,5 +1,5 @@ name: ngx-export-tools -version: 0.3.3.0 +version: 0.4.0.0 synopsis: Extra tools for Nginx haskell module description: Extra tools for .