Safe Haskell | None |
---|---|
Language | Haskell98 |
We wrap most objects in a "managed pointer", which is simply a
newtype for a ForeignPtr
of the appropriate type:
newtype Foo = Foo (ForeignPtr Foo)
Notice that types of this form are instances of
ForeignPtrNewtype
. The newtype is useful in order to make the
newtype an instance of different typeclasses. The routines in this
module deal with the memory management of such managed pointers.
- withManagedPtr :: ForeignPtrNewtype a => a -> (Ptr a -> IO c) -> IO c
- maybeWithManagedPtr :: ForeignPtrNewtype a => Maybe a -> (Ptr a -> IO c) -> IO c
- withManagedPtrList :: ForeignPtrNewtype a => [a] -> ([Ptr a] -> IO c) -> IO c
- unsafeManagedPtrGetPtr :: ForeignPtrNewtype a => a -> Ptr a
- unsafeManagedPtrCastPtr :: forall a b. ForeignPtrNewtype a => a -> Ptr b
- touchManagedPtr :: forall a. ForeignPtrNewtype a => a -> IO ()
- castTo :: forall o o'. (GObject o, GObject o') => (ForeignPtr o' -> o') -> o -> IO (Maybe o')
- unsafeCastTo :: forall o o'. (HasCallStack, GObject o, GObject o') => (ForeignPtr o' -> o') -> o -> IO o'
- newObject :: (GObject a, GObject b) => (ForeignPtr a -> a) -> Ptr b -> IO a
- wrapObject :: forall a b. (GObject a, GObject b) => (ForeignPtr a -> a) -> Ptr b -> IO a
- refObject :: (GObject a, GObject b) => a -> IO (Ptr b)
- unrefObject :: GObject a => a -> IO ()
- newBoxed :: forall a. BoxedObject a => (ForeignPtr a -> a) -> Ptr a -> IO a
- wrapBoxed :: forall a. BoxedObject a => (ForeignPtr a -> a) -> Ptr a -> IO a
- copyBoxed :: forall a. BoxedObject a => a -> IO (Ptr a)
- copyBoxedPtr :: forall a. BoxedObject a => Ptr a -> IO (Ptr a)
- freeBoxed :: forall a. BoxedObject a => a -> IO ()
- wrapPtr :: WrappedPtr a => (ForeignPtr a -> a) -> Ptr a -> IO a
- newPtr :: WrappedPtr a => (ForeignPtr a -> a) -> Ptr a -> IO a
- copyPtr :: WrappedPtr a => Int -> Ptr a -> IO (Ptr a)
Managed pointers
withManagedPtr :: ForeignPtrNewtype a => a -> (Ptr a -> IO c) -> IO c Source #
Perform an IO action on the Ptr
inside a managed pointer.
maybeWithManagedPtr :: ForeignPtrNewtype 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 :: ForeignPtrNewtype a => [a] -> ([Ptr a] -> IO c) -> IO c Source #
Perform an IO action taking a list of Ptr
on a list of managed
pointers.
unsafeManagedPtrGetPtr :: ForeignPtrNewtype a => a -> 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. ForeignPtrNewtype a => a -> Ptr b Source #
Same as unsafeManagedPtrGetPtr
, but is polymorphic on the
return type.
touchManagedPtr :: forall a. ForeignPtrNewtype 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.
Safe casting
castTo :: forall o o'. (GObject o, GObject o') => (ForeignPtr 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') => (ForeignPtr 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 :: (GObject a, GObject b) => (ForeignPtr a -> a) -> Ptr b -> IO a Source #
Construct a Haskell wrapper for a GObject
, increasing its
reference count.
wrapObject :: forall a b. (GObject a, GObject b) => (ForeignPtr a -> a) -> Ptr b -> IO a Source #
Same as newObject
, but we take ownership of the object. Newly
created GObject
s are typically floating, so we use
g_object_ref_sink.
refObject :: (GObject a, GObject b) => a -> IO (Ptr b) Source #
Increase the reference count of the given GObject
.
unrefObject :: 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.
newBoxed :: forall a. BoxedObject a => (ForeignPtr 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. BoxedObject a => (ForeignPtr 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. 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. BoxedObject a => a -> IO () Source #
Free the memory associated with a boxed object
wrapPtr :: WrappedPtr a => (ForeignPtr a -> a) -> Ptr a -> IO a Source #
Wrap a pointer, taking ownership of it.
newPtr :: WrappedPtr a => (ForeignPtr a -> a) -> Ptr a -> IO a Source #
Wrap a pointer, making a copy of the data.