diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,30 @@ +Copyright (c) 2014, João Cristóvão + +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + + * Neither the name of João Cristóvão nor the names of other + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,11 @@ +# control-concurrent-units + +Higher level interface to unbounded-delays lib, allowing you to specify +the time delays in whatever unit you prefer, us, ms, seconds, minutes, hours. + +See [this blog post for further information](http://fundeps.com/posts/haskell/2014-05-24-An-Experiment-with-Typed-Time/) + + +## Contributing + +All contribuitions are welcomed! diff --git a/Setup.hs b/Setup.hs new file mode 100644 --- /dev/null +++ b/Setup.hs @@ -0,0 +1,2 @@ +import Distribution.Simple +main = defaultMain diff --git a/src/Control/Concurrent/Units.hs b/src/Control/Concurrent/Units.hs new file mode 100644 --- /dev/null +++ b/src/Control/Concurrent/Units.hs @@ -0,0 +1,80 @@ +{-# LANGUAGE TypeFamilies #-} +-- | Higher level interface to +-- lib, allowing you to specify +-- the time delays in whatever unit you prefer, us, ms, seconds, minutes, hours. +-- See +-- All contributions are welcomed! + + +module Control.Concurrent.Units + ( threadDelay + , timeout + , Second + , milli + , micro + , Minute(..) + , Hour(..) + , Day(..) + ) where + +import qualified Control.Concurrent.Thread.Delay as Conc +import qualified Control.Concurrent.Timeout as Timeout +import Data.Metrology +import Data.Metrology.SI + + +-- | Like @Control.Concurrent.'threadDelay'@, but with a delay specified as a +-- proper time unit. +-- +-- For example: +-- +-- > threadDelay (5 %% Second |+| 40 %% milli Second) +-- +-- or +-- +-- > threadDelay (5.040 %% Second) +-- +-- There is no guarantee that the thread will be rescheduled promptly when the +-- delay has expired, but the thread will never continue to run earlier than +-- specified. +-- + +threadDelay :: Time -> IO () +threadDelay t = Conc.delay ( round $ t ## micro Second) + +-- | Like @System.Timeout.'System.Timeout.timeout'@, but with a delay specified as a +-- proper time unit. +-- +-- For example: +-- +-- > timeout (4.5 %% Hour) (reallyLongIOAction) +-- +-- Wrap an 'IO' computation to time out and return 'Nothing' in case no result is +-- available within @n@ seconds. In case a result is +-- available before the timeout expires, 'Just' @a@ is returned. A negative timeout +-- interval means \"wait indefinitely\". +-- +-- 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 :: Time -> IO a -> IO (Maybe a) +timeout t = Timeout.timeout (round $ t ## micro Second) diff --git a/unbounded-delays-units.cabal b/unbounded-delays-units.cabal new file mode 100644 --- /dev/null +++ b/unbounded-delays-units.cabal @@ -0,0 +1,39 @@ +Name: unbounded-delays-units +Version: 0.4 +Author: João Cristóvão +Maintainer: João Cristóvão +License: BSD3 +License-File: LICENSE +Synopsis: Thread delays and timeouts using proper time units +Description: + Higher level interface to unbounded-delays lib, allowing you to specify + the time delays in whatever unit you prefer, us, ms, seconds, minutes, hours. +Homepage: https://github.com/jcristovao/unbouded-delays-units +Cabal-Version: >= 1.10 +Build-Type: Simple + +extra-source-files: README.md + +Library + Default-Language: Haskell2010 + HS-Source-Dirs: src + GHC-Options: -Wall + Exposed-Modules: Control.Concurrent.Units + Build-Depends: base >= 4 && < 5 + , unbounded-delays >= 0.1.0 && < 0.2 + , units >= 2.0 && < 2.1 + , units-defs >= 1.0.1 && < 1.1 + +--Test-Suite spec + --Type: exitcode-stdio-1.0 + --Default-Language: Haskell2010 + --Hs-Source-Dirs: src + --, test + --Ghc-Options: -Wall + --Main-Is: Spec.hs + --Build-Depends: base + --, hspec + +Source-Repository head + Type: git + Location: https://github.com/jcristovao/unbounded-delays-units