Skip to content

Home

Jump to bottom
Cédric Le Moigne edited this page Nov 3, 2019 · 6 revisions

Introduction

  • the Ctypes bindings to the GObject-Introspection (all the files/modules named GISomething).

API Documentation : https://cedlemo.github.io/OCaml-GObject-Introspection/.

Implementation details

GObjectIntrospection Info Structures hierarchy and type coercion functions

GIBaseInfo
  +----GIArgInfo
  +----GICallableInfo
        +----GIFunctionInfo
        +----GISignalInfo
        +----GIVFuncInfo
  +----GIConstantInfo
  +----GIFieldInfo
  +----GIPropertyInfo
  +----GIRegisteredTypeInfo
        +----GIEnumInfo
        +----GIInterfaceInfo
        +----GIObjectInfo
        +----GIStructInfo
        +----GIUnionInfo
  +----GITypeInfo

This hierarchy determines the need to cast structures. For example GIArgInfo needs only to be casted to GIBaseInfo.

GIFunctionInfo needs to be casted to GICallableInfo and to GIBaseInfo.

So each module will (except GIBaseInfo), have functions for type coercion like:

    GIArgInfo.to_baseinfo
    GIArgInfo.from_baseinfo
    GIFunctionInfo.to_baseinfo
    GIFunctionInfo.from_baseinfo
    GIFunctionInfo.to_callableinfo
    GIFunctionInfo.from_callableinfo

How the underlying C structures allocation and deallocation are handled

When an info structure pointer is returned with full transfert via the C api, each OCaml value that wraps them is finalised with Gc.finalise for example :

let get_field info n =
  let get_field_raw =
    foreign "g_struct_info_get_field"
      (ptr structinfo @-> int @-> returning (ptr GIFieldInfo.fieldinfo)) in
  let max = get_n_fields info in
  if (n < 0 || n >= max) then raise (Failure "Array Index out of bounds")
  else let info' = get_field_raw info n in
    GIFieldInfo.add_unref_finaliser info'

So when the info' value is garbage collected, the GIFieldInfo.add_unref_finaliser is called. Here is the code of this function :

let add_unref_finaliser info =
  let _ = Gc.finalise (fun i ->
      let i' = cast_to_baseinfo i in
      GIBaseInfo.base_info_unref i') info
  in info

Each info module have this kind of function but the end user of the lib should not use them. When a cast need to be done, each module have the following two functions:

  • to_baseinfo
  • from_baseinfo

Those functions allow to transform an OCaml value that represents a GIInfo to another GIInfo type while the underlying C structure are ref"ed" and linked to a Gc finaliser that unref them. This should avoid zombies OCaml values (with C structure already desallocated) and memory leaks.

Progress

Finished

  • GIRepository — GObject Introspection repository manager
  • GIBaseInfo — Base struct for all GITypelib structs
  • GIFunctionInfo — Struct representing a function
  • GIStructInfo — Struct representing a C structure
  • GIFieldInfo — Struct representing a struct or union field
  • GIUnionInfo — Struct representing a union.
  • GIEnumInfo — Structs representing an enumeration and its values
  • GIValueInfo — Struct representing a value
  • GICallableInfo — Struct representing a callable
  • GIArgInfo — Struct representing an argument
  • GITypeInfo — Struct representing a type
  • GIConstantInfo — Struct representing a constant
  • GIObjectInfo — Struct representing a GObject
  • GIInterfaceInfo — Struct representing a GInterface
  • GIPropertyInfo — Struct representing a property
  • GISignalInfo — Struct representing a signal
  • GIVFuncInfo — Struct representing a virtual function
  • GIRegisteredTypeInfo — Struct representing a struct with a GType

Remains

  • GICallbackInfo — Struct representing a callback (no C API for now).

Resources

Clone this wiki locally