unbounded-delays-0.1.1.1: Unbounded thread delays and timeouts

Safe Haskell | Safe
Language | Haskell98

Control.Concurrent.Timeout

Description

Wait arbitrarily long for an IO computation to finish.

Synopsis

- timeout :: Integer -> IO α -> IO (Maybe α)
- data Timeout
- timeoutWithPred :: Integer -> ((Timeout -> Bool) -> IO α) -> IO (Maybe α)

# Documentation

timeout :: Integer -> IO α -> IO (Maybe α) Source #

Like `timeoutWithPred`, but does not expose the `Timeout` exception to the called action.

data Timeout Source #

#### Instances

Instances details

Exception Timeout Source # |
Instance details Defined in Control.Concurrent.Timeout Methods toException :: Timeout -> SomeException Source # fromException :: SomeException -> Maybe Timeout Source # displayException :: Timeout -> String Source # backtraceDesired :: Timeout -> Bool Source #
Show Timeout Source # |
Instance details Defined in Control.Concurrent.Timeout Methods showsPrec :: Int -> Timeout -> ShowS Source # show :: Timeout -> String Source # showList :: [Timeout] -> ShowS Source #
Eq Timeout Source # |
Instance details Defined in Control.Concurrent.Timeout Methods (==) :: Timeout -> Timeout -> Bool Source # (/=) :: Timeout -> Timeout -> Bool Source #

timeoutWithPred :: Integer -> ((Timeout -> Bool) -> IO α) -> IO (Maybe α) Source #

Like `System.Timeout.`timeout``, but not bounded by an `Int`. (..) Wrap an `IO` computation to time out and return `Nothing` in case no result is available within `n` microseconds (`1/10^6` seconds). In case a result is available before the timeout expires, `Just` `a` is returned. A negative timeout interval means "wait indefinitely".

If the computation has not terminated after `n` microseconds, it is interrupted by an asynchronous exception. The function passed to `f` can be used to detect whether it was interrupted by this timeout or some other exception.

The design of this combinator was guided by the objective that `timeout n (const f)` should behave exactly the same as `f` as long as `f` doesn't time out. This means that `f` has the same `myThreadId` it would have without the timeout wrapper. Any exceptions `f` might throw cancel the timeout and propagate further up. It also possible for `f` to receive exceptions thrown to it by another thread.

A tricky implementation detail is the question of how to abort an `IO` computation. This combinator relies on asynchronous exceptions internally. The technique works very well for computations executing inside of the Haskell runtime system, but it doesn't work at all for non-Haskell code. Foreign function calls, for example, cannot be timed out with this combinator simply because an arbitrary C function cannot receive asynchronous exceptions. When `timeout` is used to wrap an FFI call that blocks, no timeout event can be delivered until the FFI call returns, which pretty much negates the purpose of the combinator. In practice, however, this limitation is less severe than it may sound. Standard I/O functions like `hGetBuf`, `hPutBuf`, Network.Socket.accept, or `hWaitForInput` appear to be blocking, but they really don't because the runtime system uses scheduling mechanisms like `select(2)` to perform asynchronous I/O, so it is possible to interrupt standard socket I/O or file I/O using this combinator.