gwydebugobjects: Gwyddion Library Reference Manual

## gwydebugobjects gwydebugobjects — Helps chasing leaking objects (debug) |

## Functions

#define | gwy_debug_objects_creation()
void | gwy_debug_objects_creation_detailed ()
void | gwy_debug_objects_enable ()
void | gwy_debug_objects_dump_to_file ()
void | gwy_debug_objects_clear ()

## Types and Values

enum | GwyDebugObjectsDumpFlags

## Includes

    #include <libgwyddion/gwyddion.h>

## 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.

## Functions

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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).

#### Parameters

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.

## Types and Values

### enum GwyDebugObjectsDumpFlags

Option flags for `gwy_debug_objects_dump_to_file()`.

#### Members

GWY_DEBUG_OBJECTS_DUMP_ONLY_ALIVE | Dump only objects that are still alive. |