| Safe Haskell | None |
|---|---|
| Language | Haskell98 |
Data.GI.Base.ManagedPtr
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) => (ManagedPtr a -> a) -> Ptr a -> (a -> IO b) -> IO b
- unsafeManagedPtrGetPtr :: (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr a)
- unsafeManagedPtrCastPtr :: forall a b. (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr b)
- touchManagedPtr :: forall a. ManagedPtrNewtype a => a -> IO ()
- disownManagedPtr :: forall a. (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr a)
- castTo :: forall o o'. (GObject o, GObject o') => (ManagedPtr o' -> o') -> o -> IO (Maybe o')
- unsafeCastTo :: forall o o'. (HasCallStack, GObject o, GObject o') => (ManagedPtr o' -> o') -> o -> IO o'
- newObject :: (HasCallStack, GObject a, GObject b) => (ManagedPtr a -> a) -> Ptr b -> IO a
- wrapObject :: forall a b. (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 :: forall a. (HasCallStack, BoxedObject a) => (ManagedPtr a -> a) -> Ptr a -> IO a
- wrapBoxed :: forall a. (HasCallStack, BoxedObject a) => (ManagedPtr a -> a) -> Ptr a -> IO a
- copyBoxed :: forall a. (HasCallStack, BoxedObject a) => a -> IO (Ptr a)
- copyBoxedPtr :: forall a. BoxedObject a => Ptr a -> IO (Ptr a)
- freeBoxed :: forall a. (HasCallStack, BoxedObject a) => a -> IO ()
- disownBoxed :: (HasCallStack, BoxedObject a) => a -> IO (Ptr a)
- wrapPtr :: (HasCallStack, WrappedPtr a) => (ManagedPtr a -> a) -> Ptr a -> IO a
- newPtr :: (HasCallStack, WrappedPtr a) => (ManagedPtr a -> a) -> Ptr a -> IO a
- copyBytes :: WrappedPtr 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) => (ManagedPtr a -> 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 finished.
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 :: forall a b. (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr b) Source #
Same as unsafeManagedPtrGetPtr, but is polymorphic on the
return type.
touchManagedPtr :: forall a. 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 :: forall a. (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr a) Source #
Do not run the finalizers upon garbage collection of the
ManagedPtr.
Safe casting
castTo :: forall o o'. (GObject o, GObject o') => (ManagedPtr o' -> o') -> o -> IO (Maybe o') Source #
Cast to the given type, checking that the cast is valid. If it is
not, we return Nothing. Usage:
maybeWidget <- castTo Widget label
unsafeCastTo :: forall o o'. (HasCallStack, GObject o, GObject o') => (ManagedPtr o' -> o') -> o -> IO o' Source #
Cast to the given type, assuming that the cast will succeed. This
function will call error if the cast is illegal.
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.
wrapObject :: forall a b. (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 :: forall a. (HasCallStack, BoxedObject 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 :: forall a. (HasCallStack, BoxedObject 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 :: forall a. (HasCallStack, BoxedObject a) => a -> IO (Ptr a) Source #
Make a copy of the given boxed object.
copyBoxedPtr :: forall a. BoxedObject a => Ptr a -> IO (Ptr a) Source #
Like copyBoxed, but acting directly on a pointer, instead of a
managed pointer.
freeBoxed :: forall a. (HasCallStack, BoxedObject a) => a -> IO () Source #
Free the memory associated with a boxed object. Note that this
disowns the associated ManagedPtr via disownManagedPtr.
disownBoxed :: (HasCallStack, BoxedObject 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 BoxedObject.
wrapPtr :: (HasCallStack, WrappedPtr a) => (ManagedPtr a -> a) -> Ptr a -> IO a Source #
Wrap a pointer, taking ownership of it.
newPtr :: (HasCallStack, WrappedPtr a) => (ManagedPtr a -> a) -> Ptr a -> IO a Source #
Wrap a pointer, making a copy of the data.