diff --git a/System/USB/Safe.hs b/System/USB/Safe.hs --- a/System/USB/Safe.hs +++ b/System/USB/Safe.hs @@ -65,10 +65,27 @@ -------------------------------------------------------------------------------- module System.USB.Safe - ( -- * Device regions + ( -- * USB devices as scarce resources + + {-| This module provides an instance for 'Resource' for 'USB.Device'. + This allows you to open devices in a region which are automatically + closed when the region terminates but it disallows you to return handles + to these closed devices from the region so preventing I/O with closed + devices. + + Note that this module re-exports the @Control.Monad.Trans.Region@ module + from the @regions@ package which allows you to: + + * Open devices using 'open'. + + * Run regions using 'runRegionT'. + + * Concurrently run /top-level/ regions inside another region using + 'forkTopRegion'. + + * Duplicate regional device handles to a parent region using 'dup'. + -} module Control.Monad.Trans.Region - , DeviceRegionT - , TopDeviceRegion -- ** Regional device handles , RegionalDeviceHandle @@ -96,7 +113,6 @@ , getInterfaces -- ** Claiming interfaces - , IfRegionT , RegionalIfHandle , claim @@ -261,17 +277,17 @@ -- from regions: import Control.Monad.Trans.Region -import Control.Monad.Trans.Region.Internal ( Resource - , Handle - , openResource - , closeResource +import Control.Monad.Trans.Region.Unsafe ( Resource + , Handle + , openResource + , closeResource - , internalHandle + , internalHandle - , Dup + , Dup - , ParentOf - ) + , ParentOf + ) -------------------------------------------------------------------------------- -- * Device regions @@ -291,27 +307,7 @@ closeResource = USB.closeDevice ∘ internalDevHndl --- | Internally used function for getting the actual USB device handle from a --- regional device handle. -getInternalDevHndl ∷ RegionalDeviceHandle r → USB.DeviceHandle -getInternalDevHndl = internalDevHndl ∘ internalHandle -{-| Handy type synonym for a region in which USB devices can be opened which are -automatically closed when the region terminates. - -You can run a device region with 'runRegionT'. --} -type DeviceRegionT s pr α = RegionT USB.Device s pr α - -{-| Handy type synonym for a device region which has 'IO' as its parent region -which enables it to be: - - * directly executed in 'IO' using 'runTopRegion', - - * concurrently executed in a new thread by 'forkTopRegion'. --} -type TopDeviceRegion s α = TopRegion USB.Device s α - -------------------------------------------------------------------------------- -- ** Regional device handles -------------------------------------------------------------------------------- @@ -326,6 +322,11 @@ -} type RegionalDeviceHandle r = RegionalHandle USB.Device r +-- | Internally used function for getting the actual USB device handle from a +-- regional device handle. +getInternalDevHndl ∷ RegionalDeviceHandle r → USB.DeviceHandle +getInternalDevHndl = internalDevHndl ∘ internalHandle + -- | Convenience function for retrieving the device from the given regional -- handle. getDevice ∷ RegionalDeviceHandle r → USB.Device @@ -424,7 +425,7 @@ instance GetDescriptor (Config r) USB.ConfigDesc where getDesc (Config _ configDesc) = configDesc -instance Dup Config USB.Device where +instance Dup Config where dup (Config regionalDevHndlC configDesc) = do -- Duplicating a configuration just means duplicating the associated -- regional device handle: @@ -668,13 +669,6 @@ closeResource (interface → Interface {ifDevHndlI, ifNum}) = USB.releaseInterface ifDevHndlI ifNum -{-| Handy type synonym for a region in which interfaces can be claimed which are -automatically released when the region terminates. - -You can run an interface region with 'runRegionT'. --} -type IfRegionT sCfg s pr α = RegionT (Interface sCfg) s pr α - {-| Handy type synonym for a regional handle to a claimed interface. A regional handle to a claimed interface can be created by applying 'claim' or @@ -706,9 +700,9 @@ -} claim ∷ MonadCatchIO pr ⇒ Interface sCfg -- ^ Interface you wish to claim - → IfRegionT sCfg s pr - (RegionalIfHandle sCfg - (RegionT (Interface sCfg) s pr)) + → RegionT s pr + (RegionalIfHandle sCfg + (RegionT s pr)) claim = open {-| Convenience function which finds the first interface of the given @@ -720,8 +714,8 @@ ⇒ ConfigHandle sCfg -- ^ Handle to a configuration of which -- you want to claim an interface. → (USB.Interface → Bool) -- ^ Predicate on the interface descriptors. - → (∀ s. RegionalIfHandle sCfg (RegionT (Interface sCfg) s pr) - → IfRegionT sCfg s pr α + → (∀ s. RegionalIfHandle sCfg (RegionT s pr) + → RegionT s pr α ) -- ^ Continuation function. → pr α withInterfaceWhich confHndl p f = @@ -752,7 +746,7 @@ instance GetDescriptor (Alternate sIntrf r) USB.InterfaceDesc where getDesc (Alternate _ ifDesc) = ifDesc -instance Dup (Alternate sCfg) (Interface sCfg) where +instance Dup (Alternate sCfg) where dup (Alternate regionalIfHndlC ifDesc) = do regionalIfHndlP ← dup regionalIfHndlC return $ Alternate regionalIfHndlP ifDesc diff --git a/usb-safe.cabal b/usb-safe.cabal --- a/usb-safe.cabal +++ b/usb-safe.cabal @@ -1,5 +1,5 @@ name: usb-safe -version: 0.4.1 +version: 0.5 cabal-version: >=1.6 build-type: Simple license: BSD3 @@ -8,7 +8,7 @@ author: Bas van Dijk maintainer: Bas van Dijk stability: experimental -category: System +category: System, Monadic Regions synopsis: Type-safe communication with USB devices. description: The usb library provides a standard Haskell abstraction layer over @@ -108,7 +108,7 @@ , base-unicode-symbols >= 0.1.1 && < 0.2 , usb == 0.3.* , bytestring == 0.9.* - , regions == 0.1.* + , regions == 0.2.* , transformers >= 0.1.4 && < 0.2 , MonadCatchIO-transformers == 0.0.2.* exposed-modules: System.USB.Safe