Foreign.Marshal.Codensity

This library wraps the standard base bracketed allocation primitives (along with those from Data.ByteString and Data.ByteString.Short) in a Codensity-based interface to ease the chaining of complex marshalling operations.

alloca

alloca :: Storable a => Codensity IO (Ptr a)

alloca @a is a continuation that provides access to a pointer into a temporary block of memory sufficient to hold values of type a.

allocaWith :: Storable a => a -> Codensity IO (Ptr a)

allocaWith a is a continuation that provides access to a pointer into a temporary block of memory containing a.

allocaBytes :: Int -> Codensity IO (Ptr a)

allocaBytes n is a continuation that provides access to a pointer into a temporary block of memory sufficient to hold n bytes, with machine-standard alignment.

allocaBytesAligned :: Int -> Int -> Codensity IO (Ptr a)

allocaBytesAligned n a is a continuation that provides access to a pointer into a temporary block of memory sufficient to hold n bytes, with a-byte alignment.

calloc

calloc :: forall a. Storable a => Codensity IO (Ptr a)

calloc @a is a continuation that provides access to a pointer into a temporary block of zeroed memory sufficient to hold values of type a.

callocBytes :: Int -> Codensity IO (Ptr a)

callocBytes n is a continuation that provides access to a pointer into a temporary block of zeroed memory sufficient to hold n bytes, with machine-standard alignment.

allocaArray

allocaArray :: Storable a => Int -> Codensity IO (Ptr a)

allocaArray @a n is a continuation that provides access to a pointer into a temporary block of memory sufficient to hold n values of type a.

allocaArrayWith :: (Foldable f, Storable a) => f a -> Codensity IO (Ptr a)

allocaArrayWith xs is a continuation that provides access to a pointer into a temporary block of memory containing the values of xs.

allocaArrayWithOf :: Storable a => Fold s a -> s -> Codensity IO (Ptr a)

allocaArrayWithOf f works in the same way as allocaArrayWith, but using the Fold f rather than any Foldable instance.

allocaArray0 :: Storable a => Int -> Codensity IO (Ptr a)

allocaArray0 @a n is a continuation that provides access to a pointer into a temporary block of memory sufficient to hold n values of type a, along with a final terminal element.

allocaArrayWith0 :: (Foldable f, Storable a) => f a -> a -> Codensity IO (Ptr a)

allocaArrayWith0 xs end is a continuation that provides access to a pointer into a temporary block of memory containing the values of xs, terminated with end.

allocaArrayWith0Of :: Storable a => Fold s a -> s -> a -> Codensity IO (Ptr a)

allocaArrayWith0Of t works in the same way as allocaArrayWith0, but using the Fold t rather than any Foldable instance.

callocArray

callocArray :: forall a. Storable a => Int -> Codensity IO (Ptr a)

callocArray @a n is a continuation that provides access to a pointer into a temporary block of zeroed memory sufficient to hold n values of type a.

callocArray0 :: forall a. Storable a => Int -> Codensity IO (Ptr a)

callocArray0 @a n is a continuation that provides access to a pointer into a temporary block of zeroed memory sufficient to hold n values of type a, along with a final terminal element.

withForeignPtr (and alternatives)

withForeignPtr :: ForeignPtr a -> Codensity IO (Ptr a)

withForeignPtr ptr is a continuation that provides safe access to the backing pointer of ptr.

bracketCodensity :: (a -> IO b) -> (a -> IO c) -> Codensity IO a -> Codensity IO a

bracketCodensity allows one to add initialization and finalization hooks to an existing Codensity that will be executed even in cases where an exception occurs.

This provides an alternative to ForeignPtrs when the pointer will only be used in code that is written with this library in mind.

ToCString

class ToCString a where

ToCString a is a class for types a that can be encoded into CStrings.

Methods

withCString :: a -> Codensity IO CString

withCString a is a continuation that provides access to a as a CString.

withCStringLen :: a -> Codensity IO CStringLen

withCStringLen a is a continuation that provides access to a as a CStringLen.

Instances

ToCString String

Defined in Foreign.Marshal.Codensity

Methods

withCString :: String -> Codensity IO CString

withCStringLen :: String -> Codensity IO CStringLen

ToCString ShortByteString

Defined in Foreign.Marshal.Codensity

Methods

withCString :: ShortByteString -> Codensity IO CString

withCStringLen :: ShortByteString -> Codensity IO CStringLen

ToCString ByteString

Defined in Foreign.Marshal.Codensity

Methods

withCString :: ByteString -> Codensity IO CString

withCStringLen :: ByteString -> Codensity IO CStringLen

Reexports

type CString = Ptr CChar

A C string is a reference to an array of C characters terminated by NUL.

type CStringLen = (Ptr CChar, Int)

A string with explicit length information in bytes instead of a terminating NUL (allowing NUL characters in the middle of the string).

data Ptr a

A value of type Ptr a represents a pointer to an object, or an array of objects, which may be marshalled to or from Haskell values of type a.

The type a will often be an instance of class Storable which provides the marshalling operations. However this is not essential, and you can provide your own operations to access the pointer. For example you might write small foreign functions to get or set the fields of a C struct.

Instances

Generic1 (URec (Ptr ()) :: k -> Type)

Defined in GHC.Generics

Associated Types

type Rep1 (URec (Ptr ())) :: k -> Type

Methods

from1 :: URec (Ptr ()) a -> Rep1 (URec (Ptr ())) a

to1 :: Rep1 (URec (Ptr ())) a -> URec (Ptr ()) a

Eq (Ptr a)

Since: base-2.1

Defined in GHC.Ptr

Methods

(==) :: Ptr a -> Ptr a -> Bool

(/=) :: Ptr a -> Ptr a -> Bool

Ord (Ptr a)

Since: base-2.1

Defined in GHC.Ptr

Methods

compare :: Ptr a -> Ptr a -> Ordering

(<) :: Ptr a -> Ptr a -> Bool

(<=) :: Ptr a -> Ptr a -> Bool

(>) :: Ptr a -> Ptr a -> Bool

(>=) :: Ptr a -> Ptr a -> Bool

max :: Ptr a -> Ptr a -> Ptr a

min :: Ptr a -> Ptr a -> Ptr a

Show (Ptr a)

Since: base-2.1

Defined in GHC.Ptr

Methods

showsPrec :: Int -> Ptr a -> ShowS

show :: Ptr a -> String

showList :: [Ptr a] -> ShowS

Storable (Ptr a)

Since: base-2.1

Defined in Foreign.Storable

Methods

sizeOf :: Ptr a -> Int

alignment :: Ptr a -> Int

peekElemOff :: Ptr (Ptr a) -> Int -> IO (Ptr a)

pokeElemOff :: Ptr (Ptr a) -> Int -> Ptr a -> IO ()

peekByteOff :: Ptr b -> Int -> IO (Ptr a)

pokeByteOff :: Ptr b -> Int -> Ptr a -> IO ()

peek :: Ptr (Ptr a) -> IO (Ptr a)

poke :: Ptr (Ptr a) -> Ptr a -> IO ()

Functor (URec (Ptr ()) :: Type -> Type)

Since: base-4.9.0.0

Defined in GHC.Generics

Methods

fmap :: (a -> b) -> URec (Ptr ()) a -> URec (Ptr ()) b

(<$) :: a -> URec (Ptr ()) b -> URec (Ptr ()) a

Foldable (URec (Ptr ()) :: Type -> Type)

Since: base-4.9.0.0

Defined in Data.Foldable

Methods

fold :: Monoid m => URec (Ptr ()) m -> m

foldMap :: Monoid m => (a -> m) -> URec (Ptr ()) a -> m

foldr :: (a -> b -> b) -> b -> URec (Ptr ()) a -> b

foldr' :: (a -> b -> b) -> b -> URec (Ptr ()) a -> b

foldl :: (b -> a -> b) -> b -> URec (Ptr ()) a -> b

foldl' :: (b -> a -> b) -> b -> URec (Ptr ()) a -> b

foldr1 :: (a -> a -> a) -> URec (Ptr ()) a -> a

foldl1 :: (a -> a -> a) -> URec (Ptr ()) a -> a

toList :: URec (Ptr ()) a -> [a]

null :: URec (Ptr ()) a -> Bool

length :: URec (Ptr ()) a -> Int

elem :: Eq a => a -> URec (Ptr ()) a -> Bool

maximum :: Ord a => URec (Ptr ()) a -> a

minimum :: Ord a => URec (Ptr ()) a -> a

sum :: Num a => URec (Ptr ()) a -> a

product :: Num a => URec (Ptr ()) a -> a

Traversable (URec (Ptr ()) :: Type -> Type)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> URec (Ptr ()) a -> f (URec (Ptr ()) b)

sequenceA :: Applicative f => URec (Ptr ()) (f a) -> f (URec (Ptr ()) a)

mapM :: Monad m => (a -> m b) -> URec (Ptr ()) a -> m (URec (Ptr ()) b)

sequence :: Monad m => URec (Ptr ()) (m a) -> m (URec (Ptr ()) a)

Eq (URec (Ptr ()) p)

Since: base-4.9.0.0

Defined in GHC.Generics

Methods

(==) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool

(/=) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool

Ord (URec (Ptr ()) p)

Since: base-4.9.0.0

Defined in GHC.Generics

Methods

compare :: URec (Ptr ()) p -> URec (Ptr ()) p -> Ordering

(<) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool

(<=) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool

(>) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool

(>=) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool

max :: URec (Ptr ()) p -> URec (Ptr ()) p -> URec (Ptr ()) p

min :: URec (Ptr ()) p -> URec (Ptr ()) p -> URec (Ptr ()) p

Generic (URec (Ptr ()) p)

Defined in GHC.Generics

Associated Types

type Rep (URec (Ptr ()) p) :: Type -> Type

Methods

from :: URec (Ptr ()) p -> Rep (URec (Ptr ()) p) x

to :: Rep (URec (Ptr ()) p) x -> URec (Ptr ()) p

data URec (Ptr ()) (p :: k)

Used for marking occurrences of Addr#

Since: base-4.9.0.0

Defined in GHC.Generics

data URec (Ptr ()) (p :: k) = UAddr {

• uAddr# :: Addr#

}

type Rep1 (URec (Ptr ()) :: k -> Type)

Since: base-4.9.0.0

Defined in GHC.Generics

type Rep1 (URec (Ptr ()) :: k -> Type) = D1 (MetaData "URec" "GHC.Generics" "base" False) (C1 (MetaCons "UAddr" PrefixI True) (S1 (MetaSel (Just "uAddr#") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (UAddr :: k -> Type)))

type Rep (URec (Ptr ()) p)

Since: base-4.9.0.0

Defined in GHC.Generics

type Rep (URec (Ptr ()) p) = D1 (MetaData "URec" "GHC.Generics" "base" False) (C1 (MetaCons "UAddr" PrefixI True) (S1 (MetaSel (Just "uAddr#") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (UAddr :: Type -> Type)))

nullPtr :: Ptr a

The constant nullPtr contains a distinguished value of Ptr that is not associated with a valid memory location.

newtype Codensity (m :: k -> TYPE rep) a :: forall k (rep :: RuntimeRep). (k -> TYPE rep) -> Type -> Type

Codensity f is the Monad generated by taking the right Kan extension of any Functor f along itself (Ran f f).

This can often be more "efficient" to construct than f itself using repeated applications of (>>=).

See "Asymptotic Improvement of Computations over Free Monads" by Janis Voigtländer for more information about this type.

https://www.janis-voigtlaender.eu/papers/AsymptoticImprovementOfComputationsOverFreeMonads.pdf

Constructors

Codensity

Fields

• runCodensity :: forall (b :: k). (a -> m b) -> m b

Instances

MonadReader r m => MonadReader r (Codensity m)

Defined in Control.Monad.Codensity

Methods

ask :: Codensity m r

local :: (r -> r) -> Codensity m a -> Codensity m a

reader :: (r -> a) -> Codensity m a

MonadReader r m => MonadState r (Codensity m)

Defined in Control.Monad.Codensity

Methods

get :: Codensity m r

put :: r -> Codensity m ()

state :: (r -> (a, r)) -> Codensity m a

(Functor f, MonadFree f m) => MonadFree f (Codensity m)

Defined in Control.Monad.Codensity

Methods

wrap :: f (Codensity m a) -> Codensity m a

MonadTrans (Codensity :: (Type -> Type) -> Type -> Type)

Defined in Control.Monad.Codensity

Methods

lift :: Monad m => m a -> Codensity m a

Monad (Codensity f)

Defined in Control.Monad.Codensity

Methods

(>>=) :: Codensity f a -> (a -> Codensity f b) -> Codensity f b

(>>) :: Codensity f a -> Codensity f b -> Codensity f b

return :: a -> Codensity f a

fail :: String -> Codensity f a

Functor (Codensity k)

Defined in Control.Monad.Codensity

Methods

fmap :: (a -> b) -> Codensity k a -> Codensity k b

(<$) :: a -> Codensity k b -> Codensity k a

MonadFail f => MonadFail (Codensity f)

Defined in Control.Monad.Codensity

Methods

fail :: String -> Codensity f a

Applicative (Codensity f)

Defined in Control.Monad.Codensity

Methods

pure :: a -> Codensity f a

(<*>) :: Codensity f (a -> b) -> Codensity f a -> Codensity f b

liftA2 :: (a -> b -> c) -> Codensity f a -> Codensity f b -> Codensity f c

(*>) :: Codensity f a -> Codensity f b -> Codensity f b

(<*) :: Codensity f a -> Codensity f b -> Codensity f a

MonadIO m => MonadIO (Codensity m)

Defined in Control.Monad.Codensity

Methods

liftIO :: IO a -> Codensity m a

Alternative v => Alternative (Codensity v)

Defined in Control.Monad.Codensity

Methods

empty :: Codensity v a

(<|>) :: Codensity v a -> Codensity v a -> Codensity v a

some :: Codensity v a -> Codensity v [a]

many :: Codensity v a -> Codensity v [a]

Alternative v => MonadPlus (Codensity v)

Defined in Control.Monad.Codensity

Methods

mzero :: Codensity v a

mplus :: Codensity v a -> Codensity v a -> Codensity v a

Apply (Codensity f)

Defined in Control.Monad.Codensity

Methods

(<.>) :: Codensity f (a -> b) -> Codensity f a -> Codensity f b

(.>) :: Codensity f a -> Codensity f b -> Codensity f b

(<.) :: Codensity f a -> Codensity f b -> Codensity f a

liftF2 :: (a -> b -> c) -> Codensity f a -> Codensity f b -> Codensity f c

Plus v => Plus (Codensity v)

Defined in Control.Monad.Codensity

Methods

zero :: Codensity v a

Alt v => Alt (Codensity v)

Defined in Control.Monad.Codensity

Methods

(<!>) :: Codensity v a -> Codensity v a -> Codensity v a

some :: Applicative (Codensity v) => Codensity v a -> Codensity v [a]

many :: Applicative (Codensity v) => Codensity v a -> Codensity v [a]

lowerCodensity :: Applicative f => Codensity f a -> f a

This serves as the *left*-inverse (retraction) of lift.

lowerCodensity . lift ≡ id

In general this is not a full 2-sided inverse, merely a retraction, as Codensity m is often considerably "larger" than m.

e.g. Codensity ((->) s)) a ~ forall r. (a -> s -> r) -> s -> r could support a full complement of MonadState s actions, while (->) s is limited to MonadReader s actions.

Projected variants

These variants work in the same way as their corresponding functions without the terminal prime, but with a function argument that projects the results of the (possibly implicit) Fold into a Storable value.

As in the lens library, the variants beginning with an i use IndexedFolds rather than Folds, and no versions without terminal primes exist because there is no generic enough use for indexes to give a sensible default.

type AnIndexedFold i s a = forall m p. Indexable i p => p a (Const m a) -> s -> Const m s

A generic IndexedFold or equivalent, taking an IndexedGetter, IndexedFold (obviously), IndexedTraversal, or IndexedLens.

allocaArrayWith' :: (Foldable f, Storable b) => (a -> Codensity IO b) -> f a -> Codensity IO (Ptr b)

allocaArrayWithOf' :: Storable b => Fold s a -> (a -> Codensity IO b) -> s -> Codensity IO (Ptr b)

iallocaArrayWith' :: (FoldableWithIndex i f, Storable b) => (i -> a -> Codensity IO b) -> f a -> Codensity IO (Ptr b)

iallocaArrayWithOf' :: Storable b => AnIndexedFold i s a -> (i -> a -> Codensity IO b) -> s -> Codensity IO (Ptr b)

allocaArrayWith0' :: (Foldable f, Storable b) => (a -> Codensity IO b) -> f a -> b -> Codensity IO (Ptr b)

allocaArrayWith0Of' :: Storable b => Fold s a -> (a -> Codensity IO b) -> s -> b -> Codensity IO (Ptr b)

iallocaArrayWith0' :: (FoldableWithIndex i f, Storable b) => (i -> a -> Codensity IO b) -> f a -> b -> Codensity IO (Ptr b)

iallocaArrayWith0Of' :: Storable b => AnIndexedFold i s a -> (i -> a -> Codensity IO b) -> s -> b -> Codensity IO (Ptr b)