usb-safe 0.1 → 0.2

raw patch · 2 files changed

+93/−9 lines, 2 files

Files

• System/USB/Safe.hs +25/−8
• usb-safe.cabal +68/−1

@@ -58,8 +58,12 @@     ( -- * Device regions       DeviceRegionT     , runDeviceRegionT-    , forkDeviceRegionT +    , TopDeviceRegion+    , runTopDeviceRegion++    , forkTopDeviceRegion+     , mapDeviceRegionT     , liftCatch @@ -361,16 +365,28 @@ runDeviceRegionT ∷ MonadCatchIO m ⇒ (∀ s. DeviceRegionT s m α) → m α runDeviceRegionT m = runWith [] m -{-| Execute the given region in a new thread.+{-| A region which does not have parent regions and can be directly executed in+'IO' by 'runTopDeviceRegion' or concurrently executed in another region by+'forkTopDeviceRegion'.+-}+type TopDeviceRegion s = DeviceRegionT s IO +-- | Convenience funtion for running a /top-level/ region in 'IO'.+--+-- Note that: @runTopDeviceRegion = 'runDeviceRegionT'@+runTopDeviceRegion ∷ (∀ s. TopDeviceRegion s α) → IO α+runTopDeviceRegion = runDeviceRegionT++{-| Return a region which executes the given /top-level/ region in a new thread.+ Note that the forked region has the same type variable @s@ as the resulting region. This means that all 'DeviceHandle's which can be referenced in the resulting region can also be referenced in the forked region. -}-forkDeviceRegionT ∷ MonadIO m-                  ⇒ DeviceRegionT s IO ()-                  → DeviceRegionT s m ThreadId-forkDeviceRegionT m = DeviceRegionT $ do+forkTopDeviceRegion ∷ MonadIO m+                    ⇒ TopDeviceRegion s ()+                    → DeviceRegionT s m ThreadId+forkTopDeviceRegion m = DeviceRegionT $ do   openedDevicesIORef ← ask   liftIO $ do openedDevices ← readIORef openedDevicesIORef               block $ do mapM_ incrementRefCnt openedDevices@@ -729,7 +745,8 @@   * 'NoDeviceException' if the device has been disconnected - * 'SettingAlreadySet' if a configuration has already been set.+ * 'SettingAlreadySet' if a configuration has already been set using+   'withConfig' or 'withActiveConfig'.   * Another 'USBException'. -}@@ -1192,7 +1209,7 @@  {-| Control transfers can have three request types: @Standard@, @Class@ and @Vendor@. We disallow @Standard@ requests however because with them you can-destrow the safety guarantees that this module provides.+destroy the safety guarantees that this module provides. -} data RequestType = Class | Vendor 

@@ -1,5 +1,5 @@ name:          usb-safe-version:       0.1+version:       0.2 cabal-version: >=1.6 build-type:    Simple license:       BSD3@@ -10,6 +10,73 @@ stability:     experimental category:      System synopsis:      Wrapper around the usb package adding extra type-safety+description:+  The usb library provides a standard Haskell abstracting layer over+  bindings-libusb providing: abstract types instead of Ptrs, automatic+  marshalling and unmarshalling, automatic garbage collection,+  exceptions instead of integer return codes, etc..++  .++  While all that is very nice there are still some things that you can+  do wrong. For example doing I/O with a closed device or reading from+  or writing to an endpoint which doesn't belong to the claimed+  interface. Or reading from an Out endpoint or writing to an In+  endpoint.++  .++  usb-safe provides the following guarantees:++  .++  * You can't reference handles to devices that are closed. In other words: no+     I/O with closed handles is possible.++  .++  * The programmer specifies the region in which devices should remain open. On+    exit from the region the opened devices are automatically closed.++  .++  * You can't reference handles to configurations that have not been set.++  .++  * You can't reference handles to interfaces that have not been claimed.++  .++  * You can't reference handles to alternates that have not been set.++  .++  * You can't reference endpoints that don't belong to a setted alternate.++  .++  * You can't read from an endpoint with an Out transfer direction.++  .++  * You can't write to an endpoint with an In transfer direction.++  .++  * You can't read from or write to endpoints with the unsupported transfer+    types Control and Isochronous. Only I/O with endpoints with the Bulk and+    Interrupt transfer types is allowed.++  .++  The primary technique used in usb-safe is called \"Lightweight monadic+  regions\" which was invented by Oleg Kiselyov and Chung-chieh Shan.+  See:++  .++  <http://okmij.org/ftp/Haskell/regions.html#light-weight>  source-repository head   Type:     darcs