DEXTER_TIMEDSAMPLER_ERROR

#define DEXTER_TIMEDSAMPLER_ERROR dexter_timedsampler_error_quark()

The error domain of the libdexter timed sampler subsystem.

enum DexterTimedSamplerError

typedef enum {
  DEXTER_TIMEDSAMPLER_ERROR_STARTED,
  DEXTER_TIMEDSAMPLER_ERROR_NOT_STARTED,
  DEXTER_TIMEDSAMPLER_ERROR_FAILED
} DexterTimedSamplerError;

Error codes for DexterTimedSampler operations.

DexterTimedSampler

typedef struct _DexterTimedSampler DexterTimedSampler;

Opaque type with no public members.

enum DexterTimedSamplerState

typedef enum {
  DEXTER_TIMEDSAMPLER_STATE_STARTED,
  DEXTER_TIMEDSAMPLER_STATE_STOPPED,
} DexterTimedSamplerState;

All possible timed sampler states.

dexter_timedsampler_new ()

DexterTimedSampler * dexter_timedsampler_new            (const DexterPluginService *service,
                                                         guint msecs_interval,
                                                         const DexterSamplerDataCallback *callbacks,
                                                         DexterChannel *channel,
                                                         GError **error);

Creates a DexterTimedSampler implementing the indicated DexterPluginService.

The timed sampler will begin automatic sampling at each msecs_interval after dexter_timedsampler_start() is called. It will continue to sample cyclically until dexter_timedsampler_stop() is called.

If a callback array is specified, it is duplicated and stored internally (so you may free the callbacks immediately after this function). Each callback function will be called asynchronously in a thread as the timed sampler is updated cyclically.

If a channel is indicated, the timed sampler operates transparently as a proxy to a timed sampler created on the remote machine designated during channel creation. The channel must be opened with dexter_channel_open() prior to calling this function.

If no channel is indicated, the timed sampler operates locally (in-process).

The timed sampler must be freed when done with dexter_timedsampler_free().

dexter_timedsampler_free ()

void                dexter_timedsampler_free            (DexterTimedSampler *tsampler,
                                                         GError **error);

Frees a DexterTimedSampler created with dexter_timedsampler_new(). If the timed sampler is started, it will be stopped for you, although it is better form to use dexter_timedsampler_stop() before freeing the timed sampler.

If the timed sampler is operating on a channel, a message is sent to the server to free the peer. You will be notified if an error occurs during that message transmission, but the local object is always freed in any event.

dexter_timedsampler_initialize ()

gboolean            dexter_timedsampler_initialize      (DexterTimedSampler *tsampler,
                                                         const gint *param,
                                                         gconstpointer input,
                                                         GError **error);

Performs one-time initialization of the timed sampler created with dexter_timedsampler_new(). If the sampler requires simple integer data for initialization, indicate the address to that integer, or NULL, if no integer is required. If the timed sampler requires other, complex or structured input data for initialization, indicate the address to that input structure, or NULL, if no input is required.

The timed sampler should be initialized once after creation with dexter_timedsampler_new() and before starting with dexter_timedsampler_start().

If the timed sampler was created over a channel, the channel should be open when calling this function.

dexter_timedsampler_start ()

gboolean            dexter_timedsampler_start           (DexterTimedSampler *tsampler,
                                                         GError **error);

Start the timed sampler and begin receiving updates every msecs_interval, as specified in dexter_timedsampler_new(). The sampler updates recurrently until dexter_timedsampler_stop() is called.

If operating over a channel and the channel closes for any reason, the sampler state will transition to DEXTER_TIMEDSAMPLER_STATE_STOPPED.

dexter_timedsampler_stop ()

gboolean            dexter_timedsampler_stop            (DexterTimedSampler *tsampler,
                                                         GError **error);

Stops the timed sampler previously started with dexter_timedsampler_start(). If the timed sampler is already stopped, no error occurs and TRUE is returned.

dexter_timedsampler_data_new ()

gpointer            dexter_timedsampler_data_new        (DexterTimedSampler *tsampler,
                                                         gboolean populate);

Allocates memory to contain timed sampler data. The plugin implementing the timed sampler defines this structure -- it is completely opaque to the library.

If populate is TRUE, the returned memory is populated with current timed sampler data. If FALSE, it is zero-filled.

The memory must freed with dexter_timedsampler_data_free() when done, unless within a DexterSamplerDataCallback, in which case the library will free the memory for you after the callback returns.

dexter_timedsampler_data_dup ()

gpointer            dexter_timedsampler_data_dup        (DexterTimedSampler *tsampler,
                                                         gconstpointer source_data);

Allocates timed sampler data memory and copies the contents of source_data onto the new memory.

The user must free this memory with dexter_timedsampler_data_free().

dexter_timedsampler_data_xfer ()

void                dexter_timedsampler_data_xfer       (DexterTimedSampler *tsampler,
                                                         gpointer old_data,
                                                         gconstpointer new_data);

Transfers (copies) data into and/or out of the timed sampler. If old_data is indicated, the timed sampler data is copied into that memory, before being replaced with new_data. If new_data is indicated, that data will be copied over existing internal timed sampler data, after existing data is copied out to old_data.

Note that use of the new_data parameter by users is probably never appropriate. The proper way for users to replace internal timed sampler data is to start the sampler with dexter_timedsampler_start() and let it update cyclically on its own.

This api is used internally by the library to transfer network-serialized sampler data into and out of timed samplers. Users may also find it useful to copy out existing sampler data.

/* One way to get the timed sampler's current data. */
gpointer current_data = dexter_timedsampler_data_new (tsampler, TRUE);

/* Another way  */
gpointer current_data = dexter_timedsampler_data_new (tsampler, FALSE);
dexter_timedsampler_data_xfer (tsampler, current_data, NULL);

dexter_timedsampler_data_copy ()

void                dexter_timedsampler_data_copy       (DexterTimedSampler *tsampler,
                                                         gpointer dest_data,
                                                         gconstpointer source_data);

Copies the timed sampler data indicated by source_data to the memory indicated by dest_data.

dexter_timedsampler_data_free ()

void                dexter_timedsampler_data_free       (DexterTimedSampler *tsampler,
                                                         gpointer data);

Frees timed sampler data previously allocated with dexter_timedsampler_data_new() or dexter_timedsampler_data_dup().

dexter_timedsampler_input_new ()

gpointer            dexter_timedsampler_input_new       (DexterTimedSampler *tsampler);

Allocates and returns a new timed sampler input structure. The plugin implementing the timed sampler defines this structure -- it is completely opaque to the library.

The memory must be freed with dexter_timedsampler_input_free() when done.

dexter_timedsampler_input_free ()

void                dexter_timedsampler_input_free      (DexterTimedSampler *tsampler,
                                                         gpointer input);

Frees an input structure previously allocated with dexter_timedsampler_input_new().

dexter_timedsampler_get_state ()

gint                dexter_timedsampler_get_state       (DexterTimedSampler *tsampler);

Returns the current state of the timed sampler.