GtSignalLogger: libglib-testing Reference Manual

## GtSignalLogger GtSignalLogger — GObject signal logging and checking |

## Stability Level

Unstable, unless otherwise indicated

## Functions

GtSignalLogger * | gt_signal_logger_new ()
void | gt_signal_logger_free ()
gulong | gt_signal_logger_connect ()
gsize | gt_signal_logger_get_n_emissions ()
gboolean | gt_signal_logger_pop_emission ()
gchar * | gt_signal_logger_format_emission ()
gchar * | gt_signal_logger_format_emissions ()
#define | gt_signal_logger_assert_no_emissions()
#define | gt_signal_logger_assert_emission_pop()
#define | gt_signal_logger_assert_notify_emission_pop()
void | gt_signal_logger_emission_get_params ()
void | gt_signal_logger_emission_free ()

## Types and Values

| GtSignalLogger
| GtSignalLoggerEmission

## Includes

    #include <libglib-testing/signal-logger.h>

## Description

GtSignalLogger is an object which allows logging of signals emitted from zero or more GObjects, and later comparison of those signals against what was expected to be emitted.

A single GtSignalLogger instance can be used for multiple GObjects, and can outlive the objects themselves. It can be connected to several different signals, emissions of which will all be added to the same queue (ordered by emission time).

Testing of the emitted signals is performed by popping emissions off the queue and comparing them to what was expected. Macros are provided to assert that the next emission on the queue was for a specific signal — or callers may unconditionally pop the next emission and compare its properties themselves.

By default, a GtSignalLogger will not assert that its emission queue is empty on destruction: that is up to the caller, and it is highly recommended that `gt_signal_logger_assert_no_emissions()` is called before a signal logger is destroyed, or after a particular unit test is completed.

## Functions

### gt_signal_logger_new ()

    GtSignalLogger *
    gt_signal_logger_new (void);

Create a new GtSignalLogger. Add signals to it to log using `gt_signal_logger_connect()`.

#### Returns

a new GtSignalLogger.

[transfer full]

Since: 0.1.0

### gt_signal_logger_free ()

    void
    gt_signal_logger_free (GtSignalLogger *self);

Free a GtSignalLogger. This will disconnect all its closures from the signals they are connected to.

This function may be called when there are signal emissions left in the logged stack, but typically you will want to call `gt_signal_logger_assert_no_emissions()` first.

#### Parameters

self | a GtSignalLogger. | [transfer full]

Since: 0.1.0

### gt_signal_logger_connect ()

    gulong
    gt_signal_logger_connect (GtSignalLogger *self,
                              gpointer obj,
                              const gchar *signal_name);

A convenience wrapper around `g_signal_connect()` which connects the GtSignalLogger to the given `signal_name` on `obj` so that emissions of it will be logged.

The closure will be disconnected (and the returned signal connection ID invalidated) when:

- `obj` is finalised

- The closure is freed or removed

- The signal logger is freed

This does not keep a strong reference to `obj` .

#### Parameters

self | a GtSignalLogger |
obj | a GObject to connect to. | [type GObject]
signal_name | the signal on `obj` to connect to |

#### Returns

signal connection ID, as returned from `g_signal_connect()`

Since: 0.1.0

### gt_signal_logger_get_n_emissions ()

    gsize
    gt_signal_logger_get_n_emissions (GtSignalLogger *self);

Get the number of signal emissions which have been logged (and not popped) since the logger was initialised.

#### Parameters

self | a GtSignalLogger |

#### Returns

number of signal emissions

Since: 0.1.0

### gt_signal_logger_pop_emission ()

    gboolean
    gt_signal_logger_pop_emission (GtSignalLogger *self,
                                   gpointer *out_obj,
                                   gchar **out_obj_type_name,
                                   gchar **out_signal_name,
                                   GtSignalLoggerEmission **out_emission);

Pop the oldest signal emission off the stack of logged emissions, and return its object, signal name and parameters in the given return locations. All return locations are optional: if they are all `NULL`, this function just performs a pop.

If there are no signal emissions on the logged stack, `FALSE` is returned.

`out_obj` does not return a reference to the object instance, as it may have been finalised since the signal emission was logged. It should be treated as an opaque pointer. The type name of the object is given as `out_obj_type_name` , which is guaranteed to be valid.

#### Parameters

self | a GtSignalLogger |
out_obj | return location for the object instance which emitted the signal. | [out][transfer none][optional][not nullable]
out_obj_type_name | return location for the name of the type of `out_obj` . | [out][transfer full][optional][not nullable]
out_signal_name | return location for the name of the emitted signal. | [out][transfer full][optional][not nullable]
out_emission | return location for the signal emission closure containing emission parameters. | [out][transfer full][optional][not nullable]

#### Returns

`TRUE` if an emission was popped and returned, `FALSE` otherwise

Since: 0.1.0

### gt_signal_logger_format_emission ()

    gchar *
    gt_signal_logger_format_emission (gpointer obj,
                                      const gchar *obj_type_name,
                                      const gchar *signal_name,
                                      const GtSignalLoggerEmission *emission);

Format a signal emission in a human readable form, typically for logging it to some debug output.

The returned string does not have a trailing newline character (`\n`).

`obj` may have been finalised, and is just treated as an opaque pointer.

#### Parameters

obj | a GObject instance which emitted a signal |
obj_type_name | a copy of `G_OBJECT_TYPE_NAME (obj)` for use when `obj` may be invalid |
signal_name | name of the emitted signal |
emission | details of the signal emission |

#### Returns

human readable string detailing the signal emission.

[transfer full]

Since: 0.1.0

### gt_signal_logger_format_emissions ()

    gchar *
    gt_signal_logger_format_emissions (GtSignalLogger *self);

Format all the signal emissions on the logging stack in the GtSignalLogger, in a human readable format, one per line. The returned string does not end in a newline character (`\n`). Each signal emission is formatted using `gt_signal_logger_format_emission()`.

#### Parameters

self | a GtSignalLogger |

#### Returns

human readable list of all the signal emissions currently in the logger, or an empty string if the logger is empty.

[transfer full]

Since: 0.1.0

### gt_signal_logger_assert_no_emissions()

    #define             gt_signal_logger_assert_no_emissions(self)

Assert that there are no signal emissions currently in the logged stack.

#### Parameters

self | a GtSignalLogger |

Since: 0.1.0

### gt_signal_logger_assert_emission_pop()

    #define             gt_signal_logger_assert_emission_pop(self, obj, signal_name, ...)

Assert that a signal emission can be popped off the log (using `gt_signal_logger_pop_emission()`) and that it is an emission of `signal_name` on `obj` . The parameters from the emission will be returned in the return locations given in the varargs, as with `gt_signal_logger_emission_get_params()`.

If a signal emission can’t be popped, or if it doesn’t match `signal_name` and `obj` , an assertion fails, and some debug output is printed.

#### Parameters

self | a GtSignalLogger |
obj | a GObject instance to assert the emission matches |
signal_name | signal name to assert the emission matches |
... | return locations for the signal parameters |

Since: 0.1.0

### gt_signal_logger_assert_notify_emission_pop()

    #define             gt_signal_logger_assert_notify_emission_pop(self, obj, property_name)

Assert that a signal emission can be popped off the log (using `gt_signal_logger_pop_emission()`) and that it is an emission of “notify” for `property_name` on `obj` . To examine the GParamSpec for the notify emission, use `gt_signal_logger_assert_emission_pop()` instead.

If a signal emission can’t be popped, or if it doesn’t match “notify”, `property_name` and `obj` , an assertion fails, and some debug output is printed.

#### Parameters

self | a GtSignalLogger |
obj | a GObject instance to assert the emission matches |
property_name | property name to assert the “notify” signal matches |

Since: 0.1.0

### gt_signal_logger_emission_get_params ()

    void
    gt_signal_logger_emission_get_params (GtSignalLoggerEmission *self,
                                          ...);

Get the parameters emitted in this signal emission. They are returned in the return locations provided as varargs. These locations must have the right type for the parameters of the signal which was emitted.

To ignore a particular parameter, pass `NULL` as the one (or more) return locations for that parameter.

#### Parameters

self | a GtSignalLoggerEmission |
... | return locations for the signal parameters |

Since: 0.1.0

### gt_signal_logger_emission_free ()

    void
    gt_signal_logger_emission_free (GtSignalLoggerEmission *emission);

Free a GtSignalLoggerEmission.

#### Parameters

emission | a GtSignalLoggerEmission. | [transfer full]

Since: 0.1.0

## Types and Values

### GtSignalLogger

    typedef struct _GtSignalLogger GtSignalLogger;

An object which allows signal emissions from zero or more GObjects to be logged easily, without needing to write specific callback functions for any of them.

Since: 0.1.0

### GtSignalLoggerEmission

    typedef struct _GtSignalLoggerEmission GtSignalLoggerEmission;

The details of a particular signal emission, including its parameter values.

`param_values` does not include the object instance.

Since: 0.1.0