haskell-gi-base-0.26.9: Foundation for libraries generated by haskell-gi

Safe Haskell | None
Language | Haskell2010

Data.GI.Base.ManagedPtr

Contents

- Managed pointers
- Safe casting
- Wrappers

Description

We wrap most objects in a "managed pointer", which is basically a `ForeignPtr` of the appropriate type together with a notion of "disowning", which means not running the finalizers passed upon construction of the object upon garbage collection. The routines in this module deal with the memory management of such managed pointers.

Synopsis

- newManagedPtr :: HasCallStack => Ptr a -> IO () -> IO (ManagedPtr a)
- newManagedPtr' :: HasCallStack => FinalizerPtr a -> Ptr a -> IO (ManagedPtr a)
- newManagedPtr_ :: Ptr a -> IO (ManagedPtr a)
- withManagedPtr :: (HasCallStack, ManagedPtrNewtype a) => a -> (Ptr a -> IO c) -> IO c
- maybeWithManagedPtr :: (HasCallStack, ManagedPtrNewtype a) => Maybe a -> (Ptr a -> IO c) -> IO c
- withManagedPtrList :: (HasCallStack, ManagedPtrNewtype a) => [a] -> ([Ptr a] -> IO c) -> IO c
- withTransient :: (HasCallStack, ManagedPtrNewtype a) => Ptr a -> (a -> IO b) -> IO b
- unsafeManagedPtrGetPtr :: (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr a)
- unsafeManagedPtrCastPtr :: (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr b)
- touchManagedPtr :: ManagedPtrNewtype a => a -> IO ()
- disownManagedPtr :: (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr b)
- castTo :: (HasCallStack, ManagedPtrNewtype o, TypedObject o, ManagedPtrNewtype o', TypedObject o', GObject o') => (ManagedPtr o' -> o') -> o -> IO (Maybe o')
- unsafeCastTo :: (HasCallStack, ManagedPtrNewtype o, TypedObject o, ManagedPtrNewtype o', TypedObject o') => (ManagedPtr o' -> o') -> o -> IO o'
- checkInstanceType :: (ManagedPtrNewtype o, TypedObject o) => o -> GType -> IO Bool
- newObject :: (HasCallStack, GObject a, GObject b) => (ManagedPtr a -> a) -> Ptr b -> IO a
- withNewObject :: (HasCallStack, GObject o) => Ptr o -> (o -> IO b) -> IO b
- wrapObject :: (HasCallStack, GObject a, GObject b) => (ManagedPtr a -> a) -> Ptr b -> IO a
- releaseObject :: (HasCallStack, GObject a) => a -> IO ()
- unrefObject :: (HasCallStack, GObject a) => a -> IO ()
- disownObject :: (HasCallStack, GObject a) => a -> IO (Ptr b)
- newBoxed :: (HasCallStack, GBoxed a) => (ManagedPtr a -> a) -> Ptr a -> IO a
- wrapBoxed :: (HasCallStack, GBoxed a) => (ManagedPtr a -> a) -> Ptr a -> IO a
- copyBoxed :: (HasCallStack, GBoxed a) => a -> IO (Ptr a)
- copyBoxedPtr :: GBoxed a => Ptr a -> IO (Ptr a)
- freeBoxed :: (HasCallStack, GBoxed a) => a -> IO ()
- disownBoxed :: (HasCallStack, GBoxed a) => a -> IO (Ptr a)
- wrapPtr :: (HasCallStack, BoxedPtr a) => (ManagedPtr a -> a) -> Ptr a -> IO a
- newPtr :: (HasCallStack, BoxedPtr a) => (ManagedPtr a -> a) -> Ptr a -> IO a
- copyBytes :: (HasCallStack, CallocPtr a) => Int -> Ptr a -> IO (Ptr a)

# Managed pointers

newManagedPtr :: HasCallStack => Ptr a -> IO () -> IO (ManagedPtr a) Source #

Thin wrapper over `newForeignPtr`.

newManagedPtr' :: HasCallStack => FinalizerPtr a -> Ptr a -> IO (ManagedPtr a) Source #

Version of `newManagedPtr` taking a `FinalizerPtr` and a corresponding `Ptr`, as in `newForeignPtr`.

newManagedPtr_ :: Ptr a -> IO (ManagedPtr a) Source #

Thin wrapper over `newForeignPtr_`.

withManagedPtr :: (HasCallStack, ManagedPtrNewtype a) => a -> (Ptr a -> IO c) -> IO c Source #

Perform an IO action on the `Ptr` inside a managed pointer.

maybeWithManagedPtr :: (HasCallStack, ManagedPtrNewtype a) => Maybe a -> (Ptr a -> IO c) -> IO c Source #

Like `withManagedPtr`, but accepts a `Maybe` type. If the passed value is `Nothing` the inner action will be executed with a `nullPtr` argument.

withManagedPtrList :: (HasCallStack, ManagedPtrNewtype a) => [a] -> ([Ptr a] -> IO c) -> IO c Source #

Perform an IO action taking a list of `Ptr` on a list of managed pointers.

withTransient :: (HasCallStack, ManagedPtrNewtype a) => Ptr a -> (a -> IO b) -> IO b Source #

Perform the IO action with a transient managed pointer. The managed pointer will be valid while calling the action, but will be disowned as soon as the action finishes.

unsafeManagedPtrGetPtr :: (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr a) Source #

Return the `Ptr` in a given managed pointer. As the name says, this is potentially unsafe: the given `Ptr` may only be used before a call to `touchManagedPtr`. This function is of most interest to the autogenerated bindings, for hand-written code `withManagedPtr` is almost always a better choice.

unsafeManagedPtrCastPtr :: (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr b) Source #

Same as `unsafeManagedPtrGetPtr`, but is polymorphic on the return type.

touchManagedPtr :: ManagedPtrNewtype a => a -> IO () Source #

Ensure that the `Ptr` in the given managed pointer is still alive (i.e. it has not been garbage collected by the runtime) at the point that this is called.

disownManagedPtr :: (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr b) Source #

Do not run the finalizers upon garbage collection of the `ManagedPtr`.

# Safe casting

castTo :: (HasCallStack, ManagedPtrNewtype o, TypedObject o, ManagedPtrNewtype o', TypedObject o', GObject o') => (ManagedPtr o' -> o') -> o -> IO (Maybe o') Source #

Cast from one object type to another, checking that the cast is valid. If it is not, we return `Nothing`. Usage:

    maybeWidget <- castTo Widget label

unsafeCastTo :: (HasCallStack, ManagedPtrNewtype o, TypedObject o, ManagedPtrNewtype o', TypedObject o') => (ManagedPtr o' -> o') -> o -> IO o' Source #

Cast a typed object to a new type (without any assumption that both types descend from `GObject`), assuming that the cast will succeed. This function will call `error` if the cast is illegal.

checkInstanceType :: (ManagedPtrNewtype o, TypedObject o) => o -> GType -> IO Bool Source #

Check whether the given object is an instance of the given type.

# Wrappers

newObject :: (HasCallStack, GObject a, GObject b) => (ManagedPtr a -> a) -> Ptr b -> IO a Source #

Construct a Haskell wrapper for a `GObject`, increasing its reference count, or taking ownership of the floating reference if there is one.

withNewObject :: (HasCallStack, GObject o) => Ptr o -> (o -> IO b) -> IO b Source #

Perform the given IO action with a wrapped copy of the given ptr to a GObject. Note that this increases the reference count of the wrapped GObject, similarly to `newObject`.

wrapObject :: (HasCallStack, GObject a, GObject b) => (ManagedPtr a -> a) -> Ptr b -> IO a Source #

Same as `newObject`, but we steal ownership of the object.

releaseObject :: (HasCallStack, GObject a) => a -> IO () Source #

Unref the given `GObject` and disown it. Use this if you want to manually release the memory associated to a given `GObject` (assuming that no other reference to the underlying C object exists) before the garbage collector does it. It is typically not safe to access the `GObject` after calling this function.

unrefObject :: (HasCallStack, GObject a) => a -> IO () Source #

Decrease the reference count of the given `GObject`. The memory associated with the object may be released if the reference count reaches 0.

disownObject :: (HasCallStack, GObject a) => a -> IO (Ptr b) Source #

Disown a GObject, that is, do not unref the associated foreign GObject when the Haskell object gets garbage collected. Returns the pointer to the underlying GObject.

newBoxed :: (HasCallStack, GBoxed a) => (ManagedPtr a -> a) -> Ptr a -> IO a Source #

Construct a Haskell wrapper for the given boxed object. We make a copy of the object.

wrapBoxed :: (HasCallStack, GBoxed a) => (ManagedPtr a -> a) -> Ptr a -> IO a Source #

Like `newBoxed`, but we do not make a copy (we "steal" the passed object, so now it is managed by the Haskell runtime).

copyBoxed :: (HasCallStack, GBoxed a) => a -> IO (Ptr a) Source #

Make a copy of the given boxed object.

copyBoxedPtr :: GBoxed a => Ptr a -> IO (Ptr a) Source #

Like `copyBoxed`, but acting directly on a pointer, instead of a managed pointer.

freeBoxed :: (HasCallStack, GBoxed a) => a -> IO () Source #

Free the memory associated with a boxed object. Note that this disowns the associated `ManagedPtr` via `disownManagedPtr`.

disownBoxed :: (HasCallStack, GBoxed a) => a -> IO (Ptr a) Source #

Disown a boxed object, that is, do not free the associated foreign GBoxed when the Haskell object gets garbage collected. Returns the pointer to the underlying `GBoxed`.

wrapPtr :: (HasCallStack, BoxedPtr a) => (ManagedPtr a -> a) -> Ptr a -> IO a Source #

Wrap a pointer, taking ownership of it.

newPtr :: (HasCallStack, BoxedPtr a) => (ManagedPtr a -> a) -> Ptr a -> IO a Source #

Wrap a pointer, making a copy of the data.

copyBytes :: (HasCallStack, CallocPtr a) => Int -> Ptr a -> IO (Ptr a) Source #

Make a copy of a wrapped pointer using `memcpy` into a freshly allocated memory region of the given size.