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

Safe Haskell | None
Language | Haskell2010

Data.GI.Base.BasicTypes

Contents

- Memory management
- Basic GLib / GObject types

Description

Basic types used in the bindings.

Synopsis

- data ManagedPtr a = ManagedPtr {
  - managedForeignPtr :: ForeignPtr a
  - managedPtrAllocCallStack :: Maybe CallStack
  - managedPtrIsDisowned :: IORef (Maybe CallStack)
  }
- class Coercible a (ManagedPtr ()) => ManagedPtrNewtype a where
  - toManagedPtr :: a -> ManagedPtr a
- class ManagedPtrNewtype a => BoxedPtr a where
  - boxedPtrCopy :: a -> IO a
  - boxedPtrFree :: a -> IO ()
- class BoxedPtr a => CallocPtr a where
  - boxedPtrCalloc :: IO (Ptr a)
- data UnexpectedNullPointerReturn = UnexpectedNullPointerReturn {
  - nullPtrErrorMsg :: Text
  }
- class HasParentTypes a => TypedObject a where
  - glibType :: IO GType
- class (ManagedPtrNewtype a, TypedObject a) => GObject a
- newtype GType = GType {
  - gtypeToCGType :: CGType
  }
- type CGType = Word64
- gtypeName :: GType -> IO String
- newtype GVariant = GVariant (ManagedPtr GVariant)
- class (ManagedPtrNewtype a, TypedObject a) => GBoxed a
- class TypedObject a => BoxedEnum a
- class TypedObject a => BoxedFlags a
- newtype GParamSpec = GParamSpec (ManagedPtr GParamSpec)
- noGParamSpec :: Maybe GParamSpec
- data GArray a = GArray (Ptr (GArray a))
- data GPtrArray a = GPtrArray (Ptr (GPtrArray a))
- data GByteArray = GByteArray (Ptr GByteArray)
- data GHashTable a b = GHashTable (Ptr (GHashTable a b))
- data GList a = GList (Ptr (GList a))
- g_list_free :: Ptr (GList a) -> IO ()
- data GSList a = GSList (Ptr (GSList a))
- g_slist_free :: Ptr (GSList a) -> IO ()
- class Enum a => IsGFlag a
- newtype PtrWrapped a = PtrWrapped {
  - unwrapPtr :: Ptr a
  }
- type GDestroyNotify ptr = FunPtr (ptr -> IO ())
- type GHashFunc a = FunPtr (PtrWrapped a -> IO Word32)
- type GEqualFunc a = FunPtr (PtrWrapped a -> PtrWrapped a -> IO Int32)

# Memory management

data ManagedPtr a Source #

Thin wrapper over `ForeignPtr`, supporting the extra notion of `disowning`, that is, not running the finalizers associated with the foreign ptr.

Constructors

ManagedPtr |

Fields

- managedForeignPtr :: ForeignPtr a
- managedPtrAllocCallStack :: Maybe CallStack

  `CallStack` for the call that created the pointer.

- managedPtrIsDisowned :: IORef (Maybe CallStack)

  When disowned, the `CallStack` for the disowning call.

#### Instances

Instances details

Eq (ManagedPtr a) Source # | Two `ManagedPtr`s are equal if they wrap the same underlying C `Ptr`.
Instance details Defined in Data.GI.Base.BasicTypes Methods (==) :: ManagedPtr a -> ManagedPtr a -> Bool Source # (/=) :: ManagedPtr a -> ManagedPtr a -> Bool Source #

class Coercible a (ManagedPtr ()) => ManagedPtrNewtype a where Source #

A constraint ensuring that the given type is a newtype over a `ManagedPtr`.

Methods

toManagedPtr :: a -> ManagedPtr a Source #

#### Instances

Instances details

Coercible a (ManagedPtr ()) => ManagedPtrNewtype a Source # | A default instance for `IsManagedPtr` for newtypes over `ManagedPtr`.
Instance details Defined in Data.GI.Base.BasicTypes Methods toManagedPtr :: a -> ManagedPtr a Source #

class ManagedPtrNewtype a => BoxedPtr a where Source #

Pointers to chunks of memory which we know how to copy and release.

Methods

boxedPtrCopy :: a -> IO a Source #

Make a copy of the given `BoxedPtr`.

boxedPtrFree :: a -> IO () Source #

A pointer to a function for freeing the given pointer.

class BoxedPtr a => CallocPtr a where Source #

A ptr to a memory block which we know how to allocate and fill with zero.

Methods

boxedPtrCalloc :: IO (Ptr a) Source #

Allocate a zero-initialized block of memory for the given type.

data UnexpectedNullPointerReturn Source #

A common omission in the introspection data is missing (nullable) annotations for return types, when they clearly are nullable. (A common idiom is "Returns: valid value, or %NULL if something went wrong.")

Haskell wrappers will raise this exception if the return value is an unexpected `nullPtr`.

Constructors

UnexpectedNullPointerReturn |

Fields

- nullPtrErrorMsg :: Text

#### Instances

Instances details

Exception UnexpectedNullPointerReturn Source # |
Instance details Defined in Data.GI.Base.BasicTypes Methods toException :: UnexpectedNullPointerReturn -> SomeException Source # fromException :: SomeException -> Maybe UnexpectedNullPointerReturn Source # displayException :: UnexpectedNullPointerReturn -> String Source # backtraceDesired :: UnexpectedNullPointerReturn -> Bool Source #
Show UnexpectedNullPointerReturn Source # |
Instance details Defined in Data.GI.Base.BasicTypes Methods showsPrec :: Int -> UnexpectedNullPointerReturn -> ShowS Source # show :: UnexpectedNullPointerReturn -> String Source # showList :: [UnexpectedNullPointerReturn] -> ShowS Source #

# Basic GLib / GObject types

class HasParentTypes a => TypedObject a where Source #

A wrapped object that has an associated GLib type. This does not necessarily descend from `GObject`, that constraint is implemented by `GObject` below.

Methods

glibType :: IO GType Source #

The `GType` for this object.

#### Instances

Instances details

TypedObject GError Source # |
Instance details Defined in Data.GI.Base.GError Methods glibType :: IO GType Source #
TypedObject GValue Source # | Find the associated `GType` for `GValue`.
Instance details Defined in Data.GI.Base.GValue Methods glibType :: IO GType Source #
TypedObject (GClosure a) Source # | Find the associated `GType` for the given closure.
Instance details Defined in Data.GI.Base.GClosure Methods glibType :: IO GType Source #

class (ManagedPtrNewtype a, TypedObject a) => GObject a Source #

A wrapped `GObject`, or any other type that descends from it.

newtype GType Source #

A newtype for use on the Haskell side.

Constructors

GType |

Fields

- gtypeToCGType :: CGType

#### Instances

Instances details

Show GType Source # |
Instance details Defined in Data.GI.Base.BasicTypes Methods showsPrec :: Int -> GType -> ShowS Source # show :: GType -> String Source # showList :: [GType] -> ShowS Source #
Eq GType Source # |
Instance details Defined in Data.GI.Base.BasicTypes Methods (==) :: GType -> GType -> Bool Source # (/=) :: GType -> GType -> Bool Source #
IsGValue GType Source # |
Instance details Defined in Data.GI.Base.GValue Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> GType -> IO () Source # gvalueGet_ :: Ptr GValue -> IO GType Source #

type CGType = Word64 Source #

A type identifier in the GLib type system. This is the low-level type associated with the representation in memory, when using this on the Haskell side use `GType` below.

gtypeName :: GType -> IO String Source #

Get the name assigned to the given `GType`.

newtype GVariant Source #

A GVariant. See Data.GI.Base.GVariant for further methods.

Constructors

GVariant (ManagedPtr GVariant) |

#### Instances

Instances details

IsGVariant GVariant Source # |
Instance details Defined in Data.GI.Base.GVariant Methods toGVariant :: GVariant -> IO GVariant Source # fromGVariant :: GVariant -> IO (Maybe GVariant) Source # toGVariantFormatString :: GVariant -> Text Source #

class (ManagedPtrNewtype a, TypedObject a) => GBoxed a Source #

Chunks of memory whose allocation/deallocation info has been registered with the GLib type system.

#### Instances

Instances details

GBoxed GError Source # | `GError`s are registered as boxed in the GLib type system.
Instance details Defined in Data.GI.Base.GError
GBoxed GValue Source # | `GValue`s are registered as boxed in the GLib type system.
Instance details Defined in Data.GI.Base.GValue
GBoxed (GClosure a) Source # | `GClosure`s are registered as boxed in the GLib type system.
Instance details Defined in Data.GI.Base.GClosure

class TypedObject a => BoxedEnum a Source #

Enums with an associated `GType`.

class TypedObject a => BoxedFlags a Source #

Flags with an associated `GType`.

newtype GParamSpec Source #

A GParamSpec. See Data.GI.Base.GParamSpec for further methods.

Constructors

GParamSpec (ManagedPtr GParamSpec) |

#### Instances

Instances details

IsGValue (Maybe GParamSpec) Source # |
Instance details Defined in Data.GI.Base.GValue Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe GParamSpec -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe GParamSpec) Source #

noGParamSpec :: Maybe GParamSpec Source #

A convenient synonym for `Nothing :: Maybe GParamSpec`.

data GArray a Source #

A GArray. Marshalling for this type is done in Data.GI.Base.BasicConversions, it is mapped to a list on the Haskell side.

Constructors

GArray (Ptr (GArray a)) |

data GPtrArray a Source #

A GPtrArray. Marshalling for this type is done in Data.GI.Base.BasicConversions, it is mapped to a list on the Haskell side.

Constructors

GPtrArray (Ptr (GPtrArray a)) |

data GByteArray Source #

A GByteArray. Marshalling for this type is done in Data.GI.Base.BasicConversions, it is packed to a `ByteString` on the Haskell side.

Constructors

GByteArray (Ptr GByteArray) |

data GHashTable a b Source #

A GHashTable. It is mapped to a `Map` on the Haskell side.

Constructors

GHashTable (Ptr (GHashTable a b)) |

data GList a Source #

A GList, mapped to a list on the Haskell side. Marshalling is done in Data.GI.Base.BasicConversions.

Constructors

GList (Ptr (GList a)) |

g_list_free :: Ptr (GList a) -> IO () Source #

Free the given `GList`.

data GSList a Source #

A GSList, mapped to a list on the Haskell side. Marshalling is done in Data.GI.Base.BasicConversions.

Constructors

GSList (Ptr (GSList a)) |

g_slist_free :: Ptr (GSList a) -> IO () Source #

Free the given `GSList`.

class Enum a => IsGFlag a Source #

An enum usable as a flag for a function.

#### Instances

Instances details

IsGFlag GParamFlag Source # |
Instance details Defined in Data.GI.Base.GParamSpec

newtype PtrWrapped a Source #

Some APIs, such as `GHashTable`, pass around scalar types wrapped into a pointer. We encode such a type as follows.

Constructors

PtrWrapped |

Fields

- unwrapPtr :: Ptr a

type GDestroyNotify ptr = FunPtr (ptr -> IO ()) Source #

Destroy the memory pointed to by a given pointer type.

type GHashFunc a = FunPtr (PtrWrapped a -> IO Word32) Source #

A pointer to a hashing function on the C side.

type GEqualFunc a = FunPtr (PtrWrapped a -> PtrWrapped a -> IO Int32) Source #

A pointer to an equality checking function on the C side.