diff --git a/Changelog.md b/Changelog.md --- a/Changelog.md +++ b/Changelog.md @@ -1,3 +1,10 @@ +### 1.2.3.2 + +- Suggest the synchronous initialization hook *ngxExportInitHook* from + *ngx-export ≥ 1.7.10* in documentation on *voidService*. +- Added an example of using *ngxExportInitHook* in conjunction with typed simple + services. + ### 1.2.3.1 - Stick to the original polymorphic type signature of *voidHandler'* to avoid diff --git a/NgxExport/Tools/Combinators.hs b/NgxExport/Tools/Combinators.hs --- a/NgxExport/Tools/Combinators.hs +++ b/NgxExport/Tools/Combinators.hs @@ -112,8 +112,15 @@ -- @ -- -- gets loaded by service /testLoadConf/ from the Nginx configuration, then it --- can be accessed in the Haskell code via 'Data.IORef.IORef' data storage +-- can be accessed in the Haskell code via t'Data.IORef.IORef' data storage -- /storage_Conf_testLoadConf/. +-- +-- 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 +-- 'NgxExport.ngxExportInitHook' as a distinct solution or in conjunction with +-- other services. -- -- @since 1.2.3 voidService :: a -- ^ Ignored configuration diff --git a/NgxExport/Tools/SimpleService.hs b/NgxExport/Tools/SimpleService.hs --- a/NgxExport/Tools/SimpleService.hs +++ b/NgxExport/Tools/SimpleService.hs @@ -17,6 +17,9 @@ -- * Exporters of simple services -- $description + -- *** Preloading storages of typed simple services + -- $preload + -- * Exported data and functions ServiceMode (..) ,ngxExportSimpleService @@ -104,7 +107,7 @@ -- -- testConfStorage :: ByteString -> IO L.ByteString -- __/testConfStorage/__ = const $ --- showAsLazyByteString \<$\> readIORef __/storage_Conf_/__testReadConf +-- showAsLazyByteString \<$\> readIORef __/storage_Conf_testReadConf/__ -- 'ngxExportIOYY' \'testConfStorage -- -- data ConfWithDelay = ConfWithDelay { delay :: 'TimeInterval' @@ -228,6 +231,46 @@ -- > hs_testReadConfJSON: ConfJSONCon1 56 -- > Storages of service variables: -- > hs_testConfStorage: Just (Conf 20) +-- +-- $preload +-- +-- Storages of typed simple services can be preloaded /synchronously/ with +-- 'ngxExportInitHook'. This is useful if a storage gets accessed immediately +-- after the start of processing client requests in a request handler which +-- expects that the storage has already been initialized (for example, a request +-- handler may unpack the storage with 'fromJust' without checking errors). +-- +-- ==== File /test_tools.hs/: preload storage_Int_testReadInt +-- @ +-- import System.Environment +-- +-- -- ... +-- +-- initTestReadInt :: IO () +-- __/initTestReadInt/__ = do +-- _ : v : _ \<- dropWhile (\/= \"__/--testReadInt/__\") \<$\> 'System.Environment.getArgs' +-- let i = read v +-- i \`seq\` writeIORef __/storage_Int_testReadInt/__ (Just i) +-- 'ngxExportInitHook' \'initTestReadInt +-- @ +-- +-- Note that the preloaded value gets evaluated inside the hook to spot any +-- parse errors inplace before the start of processing client requests. +-- +-- ==== File /nginx.conf/: read data for storage_Int_testReadInt +-- @ +-- haskell program_options __/--testReadInt/__ 800; +-- +-- # ... +-- +-- haskell_run_service __/simpleService_testReadInt/__ +-- $hs_testReadInt +-- __/-/__; +-- @ +-- +-- The preloaded value gets passed in directive /haskell program_options/. The +-- value in the service declaration can be replaced by any lexeme as it won't +-- be parsed. In this example, it was replaced by a dash. -- | Defines a sleeping strategy. data ServiceMode @@ -361,7 +404,8 @@ -- be further accessed directly from this storage. The storage can be accessed -- from elsewhere by a name comprised of the name of the custom type and the -- name of the service connected by an underscore and prefixed as a whole word --- with __/storage_/__. The stored data is wrapped in 'Maybe' container. +-- with __/storage_/__. The stored data is wrapped in a 'Maybe' container which +-- contains 'Nothing' until the initialization on the first service run. -- -- When reading of the custom object fails on the first service run, the -- service terminates the worker process by calling 'terminateWorkerProcess' @@ -376,19 +420,20 @@ -- | Exports a simple service of type -- -- @ --- 'Data.Aeson.FromJSON' a => a -> 'Prelude.Bool' -> 'IO' 'L.ByteString' +-- t'Data.Aeson.FromJSON' a => a -> 'Prelude.Bool' -> 'IO' 'L.ByteString' -- @ -- -- with specified name and service mode. -- -- The service expects an object of a custom type implementing an instance of --- 'Data.Aeson.FromJSON' at its first argument. For the sake of efficiency, this --- object gets deserialized into a global 'IORef' data storage on the first +-- t'Data.Aeson.FromJSON' at its first argument. For the sake of efficiency, +-- this object gets deserialized into a global 'IORef' data storage on the first -- service run to be further accessed directly from this storage. The storage -- can be accessed from elsewhere by a name comprised of the name of the custom -- type and the name of the service connected by an underscore and prefixed as a --- whole word with __/storage_/__. The stored data is wrapped in 'Maybe' --- container. +-- whole word with __/storage_/__. The stored data is wrapped in a 'Maybe' +-- container which contains 'Nothing' until the initialization on the first +-- service run. -- -- When reading of the custom object fails on the first service run, the -- service terminates the worker process by calling 'terminateWorkerProcess' 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: 1.2.3.1 +version: 1.2.3.2 synopsis: Extra tools for Nginx Haskell module description: Extra tools for .