auto-update-0.1.4: Efficiently run periodic, on-demand actions

Safe Haskell | Safe
Language | Haskell2010

Control.AutoUpdate

Contents

- Type
- Accessors
- Creation

Description

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 = getCurrentTime
                 , updateFreq = 1000000 -- The default frequency, once per second
                 }
    currentTime <- getTime

For more examples, see the blog post introducing this library.

Synopsis

- data UpdateSettings a
- defaultUpdateSettings :: UpdateSettings ()
- updateAction :: UpdateSettings a -> IO a
- updateFreq :: UpdateSettings a -> Int
- updateSpawnThreshold :: UpdateSettings a -> Int
- mkAutoUpdate :: UpdateSettings a -> IO (IO a)
- mkAutoUpdateWithModify :: UpdateSettings a -> (a -> IO a) -> IO (IO a)

# Type

data UpdateSettings a #

Settings to control how values are updated.

This should be constructed using `defaultUpdateSettings` and record update syntax, e.g.:

    let settings = defaultUpdateSettings { updateAction = getCurrentTime }

Since: 0.1.0

defaultUpdateSettings :: UpdateSettings () #

Default value for creating an `UpdateSettings`.

Since: 0.1.0

# Accessors

updateAction :: UpdateSettings a -> IO a #

Action to be performed to get the current value.

Default: does nothing.

Since: 0.1.0

updateFreq :: UpdateSettings a -> Int #

Microseconds between update calls. Same considerations as `threadDelay` apply.

Default: 1 second (1000000)

Since: 0.1.0

updateSpawnThreshold :: UpdateSettings a -> 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 before we decide to spawn a dedicated thread.

Default: 3

Since: 0.1.0

# Creation

mkAutoUpdate :: UpdateSettings a -> IO (IO a) #

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

mkAutoUpdateWithModify :: UpdateSettings a -> (a -> IO a) -> IO (IO a) #

Generate an action which will either read from an automatically updated value, or run the update action in the current thread if the first time or the provided modify action after that.

Since: 0.1.4