FolksDebug

FolksDebug — Manages debug output and status reporting for all folks objects.

Functions

Properties

Signals

void print-status Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── FolksDebug

Description

All GLib debug logging calls are passed through a log handler in this class, which allows debug domains to be outputted according to whether they've been enabled by being passed to folks_debug_dup().

Functions

FOLKS_TYPE_DEBUG

#define FOLKS_TYPE_DEBUG (folks_debug_get_type ())

The type for FolksDebug.


folks_debug_emit_print_status ()

void
folks_debug_emit_print_status (FolksDebug *self);

Causes all significant objects in the library to print their current status to standard output, obeying the options set on this FolksDebug instance for colouring and other formatting.

Parameters

self

the FolksDebug instance

 

Since 0.5.1


folks_debug_indent ()

void
folks_debug_indent (FolksDebug *self);

Increment the indentation level used when printing output through the object.

This is intended to be used by backend libraries only.

Parameters

self

the FolksDebug instance

 

Since 0.5.1


folks_debug_unindent ()

void
folks_debug_unindent (FolksDebug *self);

Decrement the indentation level used when printing output through the object.

This is intended to be used by backend libraries only.

Parameters

self

the FolksDebug instance

 

Since 0.5.1


folks_debug_print_line ()

void
folks_debug_print_line (FolksDebug *self,
                        const gchar *domain,
                        GLogLevelFlags level,
                        const gchar *format,
                        ...);

Print a debug line with the current indentation level for the specified debug domain.

This is intended to be used by backend libraries only.

Parameters

...

 .

Arguments for the format string

.

[in]

self

the FolksDebug instance

 

domain

 .

The debug domain name

.

[in]

level

 .

A set of log level flags for the message

.

[in]

format

 .

A printf-style format string for the heading

.

[in]

Since 0.5.1


folks_debug_print_heading ()

void
folks_debug_print_heading (FolksDebug *self,
                           const gchar *domain,
                           GLogLevelFlags level,
                           const gchar *format,
                           ...);

Print a debug line as a heading. It will be coloured according to the current indentation level so that different levels of headings stand out.

This is intended to be used by backend libraries only.

Parameters

...

 .

Arguments for the format string

.

[in]

self

the FolksDebug instance

 

domain

 .

The debug domain name

.

[in]

level

 .

A set of log level flags for the message

.

[in]

format

 .

A printf-style format string for the heading

.

[in]

Since 0.5.1


folks_debug_print_key_value_pairs ()

void
folks_debug_print_key_value_pairs (FolksDebug *self,
                                   const gchar *domain,
                                   GLogLevelFlags level,
                                   ...);

Print a set of key–value pairs in a table. The width of the key column is automatically set to the width of the longest key. The keys and values must be provided as a null-delimited list of alternating key–value varargs. Values may be null but keys may not.

This is intended to be used by backend libraries only.

The table will be printed at the current indentation level plus one.

Parameters

...

 .

Alternating keys and values, terminated with null

.

[in]

self

the FolksDebug instance

 

domain

 .

The debug domain name

.

[in]

level

 .

A set of log level flags for the message

.

[in]

Since 0.5.1


folks_debug_get_colour_enabled ()

gboolean
folks_debug_get_colour_enabled (FolksDebug *self);

Get and return the current value of the "colour-enabled" property.

Parameters

self

the FolksDebug instance to query

 

Returns

the value of the "colour-enabled" property


folks_debug_set_colour_enabled ()

void
folks_debug_set_colour_enabled (FolksDebug *self,
                                gboolean value);

Set the value of the "colour-enabled" property to value .

Parameters

self

the FolksDebug instance to modify

 

value

the new value of the "colour-enabled" property

 

folks_debug_get_debug_output_enabled ()

gboolean
folks_debug_get_debug_output_enabled (FolksDebug *self);

Get and return the current value of the "debug-output-enabled" property.

Whether debug output is enabled. This is orthogonal to the set of enabled debug domains; filtering of debug output as a whole is done after filtering by enabled domains.

Parameters

self

the FolksDebug instance to query

 

Returns

the value of the "debug-output-enabled" property

Since 0.5.1


folks_debug_set_debug_output_enabled ()

void
folks_debug_set_debug_output_enabled (FolksDebug *self,
                                      gboolean value);

Set the value of the "debug-output-enabled" property to value .

Whether debug output is enabled. This is orthogonal to the set of enabled debug domains; filtering of debug output as a whole is done after filtering by enabled domains.

Parameters

self

the FolksDebug instance to modify

 

value

the new value of the "debug-output-enabled" property

 

Since 0.5.1


folks_debug_dup ()

FolksDebug *
folks_debug_dup (void);

Create or return the singleton FolksDebug class instance. If the instance doesn't exist already, it will be created with no debug domains enabled.

This function is thread-safe.

Returns

Singleton FolksDebug instance

Since 0.5.1


folks_debug_dup_with_flags ()

FolksDebug *
folks_debug_dup_with_flags (const gchar *debug_flags,
                            gboolean colour_enabled);

Create or return the singleton FolksDebug class instance. If the instance doesn't exist already, it will be created with the given set of debug domains enabled. Otherwise, the existing instance will have its set of enabled domains changed to the provided set.

Parameters

debug_flags

 .

A comma-separated list of debug domains to enable, or null to disable debug output

.

[in][allow-none]

colour_enabled

 .

Whether debug output should be coloured using terminal escape sequences

.

[in]

Returns

Singleton FolksDebug instance

Since 0.5.1

Types and Values

FOLKS_DEBUG_STATUS_LOG_DOMAIN

#define FOLKS_DEBUG_STATUS_LOG_DOMAIN "folks-status"

Log domain for the status messages logged as a result of calling folks_debug_emit_print_status().

This could be used in conjunction with a log handler to redirect the status information to a debug window or log file, for example.

Since 0.5.1


struct FolksDebug

struct FolksDebug;

Manages debug output and status reporting for all folks objects.

All GLib debug logging calls are passed through a log handler in this class, which allows debug domains to be outputted according to whether they've been enabled by being passed to folks_debug_dup().

Since 0.5.1


struct FolksDebugClass

struct FolksDebugClass {
	GObjectClass parent_class;
};

The class structure for FOLKS_TYPE_DEBUG. All the fields in this structure are private and should never be accessed directly.

Members

GObjectClass parent_class;

the parent class structure

 

Property Details

The “colour-enabled” property

  “colour-enabled”           gboolean

colour-enabled.

Flags: Read / Write

Default value: FALSE


The “debug-output-enabled” property

  “debug-output-enabled”     gboolean

Whether debug output is enabled. This is orthogonal to the set of enabled debug domains; filtering of debug output as a whole is done after filtering by enabled domains.

Flags: Read / Write

Default value: FALSE

Since 0.5.1

Signal Details

The “print-status” signal

void
user_function (FolksDebug *debug,
               gpointer    user_data)

Signal emitted in the main thread whenever objects should print their current status. All significant objects in the library should connect to this and print their current status in some suitable format when it's emitted.

Client processes should emit this signal by calling folks_debug_emit_print_status().

Parameters

debug

the FolksDebug instance that received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 0.5.1