libfossil
fsl_xfer_dbg Struct Reference

Internal part of fsl_sc, uplifted into its own struct to simplify proper intialization of them in downstream fsl_sc implementations. More...

#include "sync.h"

Collaboration diagram for fsl_xfer_dbg:

Data Fields

fsl_buffer b
 This is a scratch buffer solely for internal use by:
fsl_xfer_dbg_f callback
 This optional method is intended to be set by client-level code, not the sync channel implementor.
void * state
 Available in callback() implementations via ch->debug.state.

Detailed Description

Internal part of fsl_sc, uplifted into its own struct to simplify proper intialization of them in downstream fsl_sc implementations.

Definition at line 40 of file sync.h.

Field Documentation

◆ b

fsl_buffer fsl_xfer_dbg::b

This is a scratch buffer solely for internal use by:

1) library APIs like fsl_xfer_debugf()

2) fsl_sc method implementations which do not themselves call into (1) while using this buffer.

Without this, fsl_xfer_debug() becomes unduly memory-costly. This memory is owned by the library and gets cleared by fsl_sc_cleanup(). fsl_sc::cleanup() implementations may clean it up but are not required to.

Definition at line 95 of file sync.h.

◆ callback

fsl_xfer_dbg_f fsl_xfer_dbg::callback

This optional method is intended to be set by client-level code, not the sync channel implementor.

If not NULL, the library or fsl_sc implementations may emit debugging output via this function.

For output channel legibility, zMsg should always end with a newline (fsl_xfer_debug() and friends will automatically add one if needed).

Implementations are free to mangle or emit the message in any form they like.

Design note: its return type is void, but experience with binding C to Java and C++ shows that such bindings may need to propagate unexpected exceptions (e.g. resource acquisition failure, logging failure, etc.) somehow through the C API, and the conventional generic way to do that is to have a result code. In normal use, it is never expected that a debugging function fails in a way which impacts the non-debugging functionality, but if an implementation absolutely must report an error, they should call fsl_xfer_error(), and that will be propagated back from this call. Channels, however, are not required to check that after every debug call - they may assume success when the debug function is called, as the debug channel should not interfere with the sync channel's operation.

See also
fsl_xfer_debug_f_FILE()
fsl_xfer_debug_f_buffer()

Definition at line 72 of file sync.h.

◆ state

void* fsl_xfer_dbg::state

Available in callback() implementations via ch->debug.state.

This memory is not owned by this object. It's owned by whoever set this member to non-NULL.

Definition at line 80 of file sync.h.


The documentation for this struct was generated from the following file: