ngx-export-tools 0.3.3.0 → 0.4.0.0

raw patch · 3 files changed

+81/−35 lines, 3 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• Changelog.md +8/−0
• NgxExport/Tools.hs +72/−34
• ngx-export-tools.cabal +1/−1

@@ -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

@@ -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 

@@ -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         <http://github.com/lyokha/nginx-haskell-module Nginx haskell module>.