Z.IO.LowResTimer

This module provide low resolution (0.1s) timers using a timing wheel of size 128 per capability, each timer thread will automatically started or stopped based on demannd. register or cancel a timeout is O(1), and each step only need scan n/128 items given timers are registered in an even fashion. This timer is particularly suitable for high concurrent approximated IO timeout scheduling. You should not rely on it to provide timing information since it's very inaccurate. Reference: * https://github.com/netty/netty/blob/4.1/common/src/main/java/io/netty/util/HashedWheelTimer.java * http://www.cse.wustl.edu/~cdgill/courses/cs6874/TimingWheels.ppt

low resolution timers

registerLowResTimer

Arguments

:: Int

timeout in unit of 0.1s

-> IO ()

the action you want to perform, it should not block

-> IO LowResTimer

Register a new timer on current capability's timer manager, start the timing wheel if it's not turning.

If the action could block, you may want to run it in another thread. Example to kill a thread after 10s:

  registerLowResTimer 100 (forkIO $ killThread tid)

registerLowResTimer_

Arguments

:: Int

timeout in unit of 0.1s

-> IO ()

the action you want to perform, it should not block

-> IO ()

void (registerLowResTimer t action)

registerLowResTimerOn

Arguments

:: LowResTimerManager

a low resolution timer manager

-> Int

timeout in unit of 0.1s

-> IO ()

the action you want to perform, it should not block

-> IO LowResTimer

Same as registerLowResTimer, but allow you choose timer manager.

data LowResTimer

Timer registered by registerLowResTimer or registerLowResTimerOn.

queryLowResTimer :: LowResTimer -> IO Int

Query how many seconds remain before timer firing.

A return value <= 0 indictate the timer is firing or fired.

cancelLowResTimer :: LowResTimer -> IO Int

Cancel a timer, return the remaining ticks.

This function have no effect after the timer is fired.

cancelLowResTimer_ :: LowResTimer -> IO ()

void . cancelLowResTimer

timeoutLowRes

Arguments

:: Int

timeout in unit of 0.1s

-> IO a

-> IO (Maybe a)

similar to timeout, this function put a limit on time which an IO can consume.

Note timeoutLowRes is also implemented with Exception underhood, which can have some surprising effects on some devices, e.g. use timeoutLowRes with reading or writing on UVStreams may close the UVStream once a reading or writing is not able to be done in time.

timeoutLowResEx

Arguments

:: HasCallStack

=> Int

timeout in unit of 0.1s

-> IO a

-> IO a

Similar to timeoutLowRes, but raise a TimeOutException to current thread instead of return Nothing if timeout.

threadDelayLowRes :: Int -> IO ()

Similiar to threadDelay, suspends the current thread for a given number of deciseconds.

throttle

Arguments

:: Int

cache time in unit of 0.1s

-> IO a

the original IO action

-> IO (IO a)

throttled IO action

Cache result of an IO action for give time t.

This combinator is useful when you want to share IO result within a period, the action will be called on demand, and the result will be cached for t milliseconds.

One common way to get a shared periodical updated value is to start a seperate thread and do calculation periodically, but doing that will stop system from being idle, which stop idle GC from running, and in turn disable deadlock detection, which is too bad. This function solves that.

throttle_

Arguments

:: Int

cache time in unit of 0.1s

-> IO ()

the original IO action

-> IO (IO ())

throttled IO action

Throttle an IO action without caching result.

The IO action will run at leading edge. i.e. once run, during following (t/10)s throttled action will no-ops.

Note the action will run in the calling thread.

throttleTrailing_

Arguments

:: Int

-> IO ()

the original IO action

-> IO (IO ())

throttled IO action

Similar to throttle_ but run action in trailing edge

The IO action will run at trailing edge. i.e. no matter how many times throttled action are called, original action will run only once after (t/10)s.

Note the action will be run in a new created thread.

low resolution timer manager

data LowResTimerManager

getLowResTimerManager :: IO LowResTimerManager

Get a LowResTimerManager for current thread.

isLowResTimerManagerRunning :: LowResTimerManager -> IO Bool

Check if a timer manager's wheel is turning

This is mostly for testing purpose.

lowResTimerManagerCapabilitiesChanged :: IO ()

Create new low resolution timer manager on capability change.

Since low resolution timer manager is not hooked into RTS, you're responsible to call this function after you call setNumCapabilities to match timer manager array size with new capability number.

This is not a must though, when we fetch timer manager we always take a modulo.