## gwydebugobjects

gwydebugobjects — Helps chasing leaking objects (debug)

## Synopsis

    #include <libgwyddion/gwyddion.h>

    enum                GwyDebugObjectsDumpFlags;
    #define             gwy_debug_objects_creation          (o)
    void                gwy_debug_objects_creation_detailed (GObject *object,
                                                             const gchar *details);
    void                gwy_debug_objects_enable            (gboolean enable);
    void                gwy_debug_objects_dump_to_file      (FILE *filehandle,
                                                             GwyDebugObjectsDumpFlags flags);
    void                gwy_debug_objects_clear             (void);

## Description

If you wonder about some object lifetime rules, these functions can help you: `gwy_debug_objects_creation()` hooks object finalization so it is possible to tell later whether and when the object was destroyed -- use `gwy_debug_objects_dump_to_file()` to dump this information to a file.

If debugging is not enabled with `gwy_debug_objects_enable()` these functions do nothing. Note all Gwyddion data-like objects (i.e., not widgets) already call `gwy_debug_objects_creation()` so to debug their lifetime rules, just enable it.

Future changes: This functionality will be removed in 3.0. Use RefDbg.

## Details

### enum GwyDebugObjectsDumpFlags

    typedef enum {
        GWY_DEBUG_OBJECTS_DUMP_ONLY_ALIVE = 1 << 0
    } GwyDebugObjectsDumpFlags;

Option flags for `gwy_debug_objects_dump_to_file()`.

`GWY_DEBUG_OBJECTS_DUMP_ONLY_ALIVE` | Dump only objects that are still alive.

### gwy_debug_objects_creation()

    #define             gwy_debug_objects_creation(o)

Convenience wrapper for `gwy_debug_objects_creation_detailed()`.

It uses file name and line number as the detail.

`o` : | An object to watch.

### gwy_debug_objects_creation_detailed ()

    void                gwy_debug_objects_creation_detailed (GObject *object,
                                                             const gchar *details);

Notes down `object` and sets up watch for its destruction.

This function should be called on object creation to get accurate creation time, but can be in fact called anytime in object existence.

There are two possible uses: In class implementation, where it should be put into instance init function. Constructors are less suited for that, as there can be more than one, there can be deserializators, duplicators, etc., and you usually want to catch all possible means of object creation.

Or it can be used on the side of object user who is concerned with lifetime rules of a particular object, he then calls it just after object creation.

`object` : | An object to watch.
`details` : | Detailed information printed in debug output. No copy is made, it must exist permanently.

### gwy_debug_objects_enable ()

    void                gwy_debug_objects_enable            (gboolean enable);

Enables or disables the object creation/destruction debugger.

When debugger is disabled, no new objects are noted, but destruction of already watched ones is still noted.

`enable` : | Whether object creation/destruction debugger should be enabled.

### gwy_debug_objects_dump_to_file ()

    void                gwy_debug_objects_dump_to_file      (FILE *filehandle,
                                                             GwyDebugObjectsDumpFlags flags);

Dumps all recorded objects to a file.

The format of each line is: object type name, object address, creation time, destruction time (or ALIVE! message with reference count).

`filehandle` : | A filehandle open for writing.
`flags` : | Dump option flags.

### gwy_debug_objects_clear ()

    void                gwy_debug_objects_clear             (void);

Frees all memory taken by debugger, removes all watches.

Eventual following call to `gwy_debug_objects_creation()` will behave like the very first one, including time counting reset.