Hello community, here is the log from the commit of package ghc-auto-update for openSUSE:Factory checked in at 2016-04-30 23:30:10 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Comparing /work/SRC/openSUSE:Factory/ghc-auto-update (Old) and /work/SRC/openSUSE:Factory/.ghc-auto-update.new (New) ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Package is "ghc-auto-update" Changes: -------- --- /work/SRC/openSUSE:Factory/ghc-auto-update/ghc-auto-update.changes 2016-01-07 00:25:28.000000000 +0100 +++ /work/SRC/openSUSE:Factory/.ghc-auto-update.new/ghc-auto-update.changes 2016-04-30 23:30:12.000000000 +0200 @@ -1,0 +2,6 @@ +Tue Apr 26 08:09:36 UTC 2016 - [email protected] + +- update to 0.1.3.1 +* Doc improvements + +------------------------------------------------------------------- Old: ---- auto-update-0.1.3.tar.gz New: ---- auto-update-0.1.3.1.tar.gz ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Other differences: ------------------ ++++++ ghc-auto-update.spec ++++++ --- /var/tmp/diff_new_pack.azeNDe/_old 2016-04-30 23:30:12.000000000 +0200 +++ /var/tmp/diff_new_pack.azeNDe/_new 2016-04-30 23:30:12.000000000 +0200 @@ -19,7 +19,7 @@ %global pkg_name auto-update Name: ghc-auto-update -Version: 0.1.3 +Version: 0.1.3.1 Release: 0 Summary: Efficiently run periodic, on-demand actions License: MIT ++++++ auto-update-0.1.3.tar.gz -> auto-update-0.1.3.1.tar.gz ++++++ diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/auto-update-0.1.3/ChangeLog.md new/auto-update-0.1.3.1/ChangeLog.md --- old/auto-update-0.1.3/ChangeLog.md 2015-12-16 07:13:54.000000000 +0100 +++ new/auto-update-0.1.3.1/ChangeLog.md 2016-04-25 15:26:28.000000000 +0200 @@ -1,2 +1,11 @@ -__0.1.3__ Adding a new AIP - reaperKill -__0.1.2__ Added Control.Debounce +## 0.1.3.1 + +* Doc improvements + +## 0.1.3 + +* Adding a new AIP - reaperKill + +## 0.1.2 + +* Added Control.Debounce diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/auto-update-0.1.3/Control/AutoUpdate.hs new/auto-update-0.1.3.1/Control/AutoUpdate.hs --- old/auto-update-0.1.3/Control/AutoUpdate.hs 2015-12-16 07:13:54.000000000 +0100 +++ new/auto-update-0.1.3.1/Control/AutoUpdate.hs 2016-04-24 15:33:08.000000000 +0200 @@ -1,21 +1,40 @@ --- | A common problem is the desire to have an action run at a scheduled --- interval, but only if it is needed. For example, instead of having --- every web request result in a new @getCurrentTime@ call, we'd like to --- have a single worker thread run every second, updating an @IORef@. --- However, if the request frequency is less than once per second, this is --- a pessimization, and worse, kills idle GC. --- --- This library allows you to define actions which will either be --- performed by a dedicated thread or, in times of low volume, will be --- executed by the calling thread. +-- | In a multithreaded environment, running actions on a regularly scheduled +-- background thread can dramatically improve performance. +-- For example, web servers need to return the current time with each HTTP response. +-- For a high-volume server, it's much faster for a dedicated thread to run every +-- second, and write the current time to a shared 'IORef', than it is for each +-- request to make its own call to 'getCurrentTime'. +-- +-- But for a low-volume server, whose request frequency is less than once per +-- second, that approach will result in /more/ calls to 'getCurrentTime' than +-- necessary, and worse, kills idle GC. +-- +-- This library solves that problem by allowing you to define actions which will +-- either be performed by a dedicated thread, or, in times of low volume, will +-- be executed by the calling thread. +-- +-- Example usage: +-- +-- @ +-- import "Data.Time" +-- import "Control.AutoUpdate" +-- +-- getTime <- 'mkAutoUpdate' 'defaultUpdateSettings' +-- { 'updateAction' = 'Data.Time.Clock.getCurrentTime' +-- , 'updateFreq' = 1000000 -- The default frequency, once per second +-- } +-- currentTime <- getTime +-- @ +-- +-- For more examples, <http://www.yesodweb.com/blog/2014/08/announcing-auto-update see the blog post introducing this library>. module Control.AutoUpdate ( -- * Type UpdateSettings , defaultUpdateSettings -- * Accessors + , updateAction , updateFreq , updateSpawnThreshold - , updateAction -- * Creation , mkAutoUpdate ) where @@ -27,9 +46,9 @@ import Control.Monad (void) import Data.IORef (newIORef, readIORef, writeIORef) --- | Default value for creating an @UpdateSettings@. +-- | Default value for creating an 'UpdateSettings'. -- --- Since 0.1.0 +-- @since 0.1.0 defaultUpdateSettings :: UpdateSettings () defaultUpdateSettings = UpdateSettings { updateFreq = 1000000 @@ -39,44 +58,44 @@ -- | Settings to control how values are updated. -- --- This should be constructed using @defaultUpdateSettings@ and record +-- This should be constructed using 'defaultUpdateSettings' and record -- update syntax, e.g.: -- -- @ --- let set = defaultUpdateSettings { updateAction = getCurrentTime } +-- let settings = 'defaultUpdateSettings' { 'updateAction' = 'Data.Time.Clock.getCurrentTime' } -- @ -- --- Since 0.1.0 +-- @since 0.1.0 data UpdateSettings a = UpdateSettings { updateFreq :: Int -- ^ Microseconds between update calls. Same considerations as - -- @threadDelay@ apply. + -- 'threadDelay' apply. -- -- Default: 1 second (1000000) -- - -- Since 0.1.0 + -- @since 0.1.0 , updateSpawnThreshold :: Int -- ^ NOTE: This value no longer has any effect, since worker threads are -- dedicated instead of spawned on demand. -- - -- Previously, this determined: How many times the data must be requested + -- Previously, this determined how many times the data must be requested -- before we decide to spawn a dedicated thread. -- -- Default: 3 -- - -- Since 0.1.0 + -- @since 0.1.0 , updateAction :: IO a -- ^ Action to be performed to get the current value. -- -- Default: does nothing. -- - -- Since 0.1.0 + -- @since 0.1.0 } -- | Generate an action which will either read from an automatically -- updated value, or run the update action in the current thread. -- --- Since 0.1.0 +-- @since 0.1.0 mkAutoUpdate :: UpdateSettings a -> IO (IO a) mkAutoUpdate us = do -- A baton to tell the worker thread to generate a new value. @@ -158,7 +177,7 @@ -- we have a current value, use it Right val -> return val --- | Turn a runtime exception into an impure exception, so that all @IO@ +-- | Turn a runtime exception into an impure exception, so that all 'IO' -- actions will complete successfully. This simply defers the exception until -- the value is forced. catchSome :: IO a -> IO a diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/auto-update-0.1.3/Control/Debounce.hs new/auto-update-0.1.3.1/Control/Debounce.hs --- old/auto-update-0.1.3/Control/Debounce.hs 2015-12-16 07:13:54.000000000 +0100 +++ new/auto-update-0.1.3.1/Control/Debounce.hs 2016-04-24 15:33:08.000000000 +0200 @@ -3,10 +3,26 @@ -- period of time. -- -- This is useful as an optimization, for example to ensure that logs are only --- flushed to disk at most once per second. See the fast-logger package for an --- example usage. +-- flushed to disk at most once per second. -- --- Since 0.1.2 +-- Example usage: +-- +-- @ +-- printString <- 'mkDebounce' 'defaultDebounceSettings' +-- { 'debounceAction' = putStrLn "Running action" +-- , 'debounceFreq' = 5000000 -- 5 seconds +-- } +-- @ +-- +-- >>> printString +-- Running action +-- >>> printString +-- <Wait five seconds> +-- Running action +-- +-- See the fast-logger package ("System.Log.FastLogger") for real-world usage. +-- +-- @since 0.1.2 module Control.Debounce ( -- * Type DebounceSettings @@ -25,14 +41,14 @@ -- | Settings to control how debouncing should work. -- --- This should be constructed using @defaultDebounceSettings@ and record +-- This should be constructed using 'defaultDebounceSettings' and record -- update syntax, e.g.: -- -- @ --- let set = defaultDebounceSettings { debounceAction = flushLog } +-- let settings = 'defaultDebounceSettings' { 'debounceAction' = flushLog } -- @ -- --- Since 0.1.2 +-- @since 0.1.2 data DebounceSettings = DebounceSettings { debounceFreq :: Int -- ^ Microseconds lag required between subsequence calls to the debounced @@ -40,7 +56,7 @@ -- -- Default: 1 second (1000000) -- - -- Since 0.1.2 + -- @since 0.1.2 , debounceAction :: IO () -- ^ Action to be performed. -- @@ -48,12 +64,12 @@ -- -- Default: does nothing. -- - -- Since 0.1.2 + -- @since 0.1.2 } --- | Default value for creating a @DebounceSettings@. +-- | Default value for creating a 'DebounceSettings'. -- --- Since 0.1.2 +-- @since 0.1.2 defaultDebounceSettings :: DebounceSettings defaultDebounceSettings = DebounceSettings { debounceFreq = 1000000 @@ -64,7 +80,7 @@ -- performed. The action will either be performed immediately, or after the -- current cooldown period has expired. -- --- Since 0.1.2 +-- @since 0.1.2 mkDebounce :: DebounceSettings -> IO (IO ()) mkDebounce (DebounceSettings freq action) = do baton <- newEmptyMVar diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/auto-update-0.1.3/Control/Reaper.hs new/auto-update-0.1.3.1/Control/Reaper.hs --- old/auto-update-0.1.3/Control/Reaper.hs 2015-12-16 07:13:54.000000000 +0100 +++ new/auto-update-0.1.3.1/Control/Reaper.hs 2016-04-25 15:20:34.000000000 +0200 @@ -3,8 +3,18 @@ -- | This module provides the ability to create reapers: dedicated cleanup -- threads. These threads will automatically spawn and die based on the --- presence of a workload to process on. +-- presence of a workload to process on. Example uses include: +-- +-- * Killing long-running jobs +-- * Closing unused connections in a connection pool +-- * Pruning a cache of old items (see example below) +-- +-- For real-world usage, search the <https://github.com/yesodweb/wai WAI family of packages> +-- for imports of "Control.Reaper". module Control.Reaper ( + -- * Example: Regularly cleaning a cache + -- $example1 + -- * Settings ReaperSettings , defaultReaperSettings @@ -33,7 +43,7 @@ -- be a list of @item@s. This is encouraged by 'defaultReaperSettings' and -- 'mkListAction'. -- --- Since 0.1.1 +-- @since 0.1.1 data ReaperSettings workload item = ReaperSettings { reaperAction :: workload -> IO (workload -> workload) -- ^ The action to perform on a workload. The result of this is a @@ -46,38 +56,38 @@ -- temporary workload. This is incredibly useless; you should -- definitely override this default. -- - -- Since 0.1.1 + -- @since 0.1.1 , reaperDelay :: {-# UNPACK #-} !Int -- ^ Number of microseconds to delay between calls of 'reaperAction'. -- -- Default: 30 seconds. -- - -- Since 0.1.1 + -- @since 0.1.1 , reaperCons :: item -> workload -> workload -- ^ Add an item onto a workload. -- -- Default: list consing. -- - -- Since 0.1.1 + -- @since 0.1.1 , reaperNull :: workload -> Bool -- ^ Check if a workload is empty, in which case the worker thread -- will shut down. -- -- Default: 'null'. -- - -- Since 0.1.1 + -- @since 0.1.1 , reaperEmpty :: workload -- ^ An empty workload. -- -- Default: empty list. -- - -- Since 0.1.1 + -- @since 0.1.1 } -- | Default @ReaperSettings@ value, biased towards having a list of work -- items. -- --- Since 0.1.1 +-- @since 0.1.1 defaultReaperSettings :: ReaperSettings [item] item defaultReaperSettings = ReaperSettings { reaperAction = \wl -> return (wl ++) @@ -104,11 +114,11 @@ data State workload = NoReaper -- ^ No reaper thread | Workload workload -- ^ The current jobs --- | Create a reaper addition function. This funciton can be used to add +-- | Create a reaper addition function. This function can be used to add -- new items to the workload. Spawning of reaper threads will be handled -- for you automatically. -- --- Since 0.1.1 +-- @since 0.1.1 mkReaper :: ReaperSettings workload item -> IO (Reaper workload item) mkReaper settings@ReaperSettings{..} = do stateRef <- newIORef NoReaper @@ -187,7 +197,7 @@ -- return either a new work item, or @Nothing@ if the work item is -- expired. -- --- Since 0.1.1 +-- @since 0.1.1 mkListAction :: (item -> IO (Maybe item')) -> [item] -> IO ([item'] -> [item']) @@ -202,3 +212,68 @@ Nothing -> front Just y -> front . (y:) go front' xs + +-- $example1 +-- In this example code, we use a 'Data.Map.Strict.Map' to cache fibonacci numbers, and a 'Reaper' to prune the cache. +-- +-- The @main@ function first creates a 'Reaper', with fields to initialize the +-- cache ('reaperEmpty'), add items to it ('reaperCons'), and prune it ('reaperAction'). +-- The reaper will run every two seconds ('reaperDelay'), but will stop running while +-- 'reaperNull' is true. +-- +-- @main@ then loops infinitely ('Control.Monad.forever'). Each second it calculates the fibonacci number +-- for a value between 30 and 34, first trying the cache ('reaperRead' and 'Data.Map.Strict.lookup'), +-- then falling back to manually calculating it (@fib@) +-- and updating the cache with the result ('reaperAdd') +-- +-- @clean@ simply removes items cached for more than 10 seconds. +-- This function is where you would perform IO-related cleanup, +-- like killing threads or closing connections, if that was the purpose of your reaper. +-- +-- @ +-- module Main where +-- +-- import "Data.Time" (UTCTime, getCurrentTime, diffUTCTime) +-- import "Control.Reaper" +-- import "Control.Concurrent" (threadDelay) +-- import "Data.Map.Strict" (Map) +-- import qualified "Data.Map.Strict" as Map +-- import "Control.Monad" (forever) +-- import "System.Random" (getStdRandom, randomR) +-- +-- fib :: 'Int' -> 'Int' +-- fib 0 = 0 +-- fib 1 = 1 +-- fib n = fib (n-1) + fib (n-2) +-- +-- type Cache = 'Data.Map.Strict.Map' 'Int' ('Int', 'Data.Time.Clock.UTCTime') +-- +-- main :: IO () +-- main = do +-- reaper <- 'mkReaper' 'defaultReaperSettings' +-- { 'reaperEmpty' = Map.'Data.Map.Strict.empty' +-- , 'reaperCons' = \\(k, v, time) workload -> Map.'Data.Map.Strict.insert' k (v, time) workload +-- , 'reaperAction' = clean +-- , 'reaperDelay' = 1000000 * 2 -- Clean every 2 seconds +-- , 'reaperNull' = Map.'Data.Map.Strict.null' +-- } +-- forever $ do +-- fibArg <- 'System.Random.getStdRandom' ('System.Random.randomR' (30,34)) +-- cache <- 'reaperRead' reaper +-- let cachedResult = Map.'Data.Map.Strict.lookup' fibArg cache +-- case cachedResult of +-- 'Just' (fibResult, _createdAt) -> 'putStrLn' $ "Found in cache: `fib " ++ 'show' fibArg ++ "` " ++ 'show' fibResult +-- 'Nothing' -> do +-- let fibResult = fib fibArg +-- 'putStrLn' $ "Calculating `fib " ++ 'show' fibArg ++ "` " ++ 'show' fibResult +-- time <- 'Data.Time.Clock.getCurrentTime' +-- ('reaperAdd' reaper) (fibArg, fibResult, time) +-- 'threadDelay' 1000000 -- 1 second +-- +-- -- Remove items > 10 seconds old +-- clean :: Cache -> IO (Cache -> Cache) +-- clean oldMap = do +-- currentTime <- 'Data.Time.Clock.getCurrentTime' +-- let pruned = Map.'Data.Map.Strict.filter' (\\(_, createdAt) -> currentTime \`diffUTCTime\` createdAt < 10.0) oldMap +-- return (\\newData -> Map.'Data.Map.Strict.union' pruned newData) +-- @ \ No newline at end of file diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/auto-update-0.1.3/auto-update.cabal new/auto-update-0.1.3.1/auto-update.cabal --- old/auto-update-0.1.3/auto-update.cabal 2015-12-16 07:13:54.000000000 +0100 +++ new/auto-update-0.1.3.1/auto-update.cabal 2016-04-25 15:26:32.000000000 +0200 @@ -1,5 +1,5 @@ name: auto-update -version: 0.1.3 +version: 0.1.3.1 synopsis: Efficiently run periodic, on-demand actions description: API docs and the README are available at <http://www.stackage.org/package/auto-update>. homepage: https://github.com/yesodweb/wai
