Log4gNDC

Log4gNDC — Nested data context

Synopsis

                    Log4gNDC;
                    Log4gNDCClass;
void                log4g_ndc_clear                     (void);
GArray *            log4g_ndc_clone                     (void);
void                log4g_ndc_inherit                   (GArray *stack);
const gchar *       log4g_ndc_get                       (void);
guint               log4g_ndc_size                      (void);
const gchar *       log4g_ndc_pop                       (void);
const gchar *       log4g_ndc_peek                      (void);
void                log4g_ndc_push                      (const char *message,
                                                         ...);
void                log4g_ndc_remove                    (void);
void                log4g_ndc_set_max_depth             (guint maxdepth);

Description

The NDC class implements nested data contexts. A nested data context (NDC for short) is an instrument to distinguish interleaved log output from different sources. An example of interleaved log output may occur when a server handles multiple simultaneous connections.

Nested diagnostic contexts are handled on a per-thread basis. Calling log4g_ndc_push(), log4g_ndc_pop(), and log4g_ndc_clear() do not affect the NDCs of other threads.

Contexts are nested. When enting a context, call log4g_ndc_push(). If there is currently no NDC for the current thread, one is created as a side-effect.

When leaving a context call log4g_ndc_pop().

To clear the current context call log4g_ndc_clear().

Note

It is not necessary to call log4g_ndc_clear() when exiting a thread. NDCs are automatically removed when a thread exits.

Log4gPatternLayout & Log4gTTCCLayout may be configured to automatically retrieve the the nested data context for the current thread without user intervention.

Child threads do not automatically inherit the NDC of their parent. To force a thread to inherit a nested data context use log4g_ndc_clone() & log4g_ndc_inherit().

Details

Log4gNDC

typedef struct {
} Log4gNDC;

The Log4gNDC structure does not have any public members.

Log4gNDCClass

typedef struct {
} Log4gNDCClass;

The Log4gNDCClass structure does not have any public members.

log4g_ndc_clear ()

void                log4g_ndc_clear                     (void);

Clear current nested data context.

This function is useful when a thread is used again in a different unrelated context (e.g. thread pools).

Since 0.1

log4g_ndc_clone ()

GArray *            log4g_ndc_clone                     (void);

Clone the current nested data context.

Another thread may inherit the value returned by this function by calling log4g_ndc_inherit().

Note

The caller is responsible for calling g_array_free() or log4g_ndc_inherit() for the returned value.

Returns :

A clone of the current nested data context.

Since 0.1

log4g_ndc_inherit ()

void                log4g_ndc_inherit                   (GArray *stack);

Inherit a cloned nested data context.

Note

After calling this function the caller should no longer reference stack.

See: log4g_ndc_clone()

stack :

A cloned nested data context.

Since 0.1

log4g_ndc_get ()

const gchar *       log4g_ndc_get                       (void);

Retrieve the current diagnostic context formatted as a string.

Note

You should call log4g_logging_event_get_ndc() instead of this function.

Returns :

The current diagnostic context.

Since 0.1

log4g_ndc_size ()

guint               log4g_ndc_size                      (void);

Retrieve the size (depth) of the current nested data context.

Returns :

The number of elements on the nested data context stack.

Since 0.1

log4g_ndc_pop ()

const gchar *       log4g_ndc_pop                       (void);

Call this function before leaving a diagnostic context.

The returned value is the the value that most recently added with log4g_ndc_push(). If no context is available, this function returns NULL.

Returns :

The innermost diagnostic context.

Since 0.1

log4g_ndc_peek ()

const gchar *       log4g_ndc_peek                      (void);

Look at the innermost diagnostic context without removing it.

The returned value is the the value that most recently added with log4g_ndc_push(). If no context is available, this function returns NULL.

Returns :

The innermost diagnostic context.

Since 0.1

log4g_ndc_push ()

void                log4g_ndc_push                      (const char *message,
                                                         ...);

Push new diagnostic context information for the current thread.

`message` :	A NDC message (accepts printf formats).
`...` :	Format parameters.

Since 0.1

log4g_ndc_remove ()

void                log4g_ndc_remove                    (void);

Remove all diagnostic context for the current thread.

Since 0.1

log4g_ndc_set_max_depth ()

void                log4g_ndc_set_max_depth             (guint maxdepth);

Set the maximum depth of the current diagnostic context.

If the current depth is smaller or equal to maxdepth then no action is taken.

This function is a convenient alternative to calling log4g_ndc_pop() multiple times. The following code example will preserve the depth of the diagnostic context stack after a complex sequence of calls:

void foo()
{
    guint depth = log4g_ndc_get_size();
    ... complex sequence of calls ...
    log4g_ndc_set_max_depth(depth);
}

maxdepth :

The new size to truncate the context stack to.

Since 0.1

			Log4g Reference Manual
Top \| Description