module Access.System.Timeout
    ( module System.Timeout

    , TimeoutAccess(..)
    ) where


import           System.Timeout

import           Access.Core


class Access io => TimeoutAccess io where
    timeout' :: Int -> IO a -> io (Maybe a)


instance TimeoutAccess IO where
    -- |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\". When specifying long timeouts,
    -- be careful not to exceed @maxBound :: Int@.
    --
    -- The design of this combinator was guided by the objective that @timeout n 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 'System.IO.hGetBuf', 'System.IO.hPutBuf', Network.Socket.accept, or
    -- 'System.IO.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.
    timeout' = timeout