Samplers

Samplers — Using samplers for data snapshots

Synopsis

#include <dexter.h>

#define             DEXTER_SAMPLER_ERROR
enum                DexterSamplerError;

                    DexterSampler;

void                (*DexterSamplerDataCallback)        (gpointer sampler,
                                                         gpointer sampler_data);

DexterSampler *     dexter_sampler_new                  (const DexterPluginService *service,
                                                         const DexterSamplerDataCallback *callbacks,
                                                         DexterChannel *channel,
                                                         GError **error);
void                dexter_sampler_free                 (DexterSampler *sampler,
                                                         GError **error);
gboolean            dexter_sampler_initialize           (DexterSampler *sampler,
                                                         const gint *param,
                                                         gconstpointer input,
                                                         GError **error);
gboolean            dexter_sampler_sample               (DexterSampler *sampler,
                                                         GError **error);
gpointer            dexter_sampler_data_new             (DexterSampler *sampler,
                                                         gboolean populate);
gpointer            dexter_sampler_data_dup             (DexterSampler *sampler,
                                                         gconstpointer source_data);
void                dexter_sampler_data_xfer            (DexterSampler *sampler,
                                                         gpointer old_data,
                                                         gconstpointer new_data);
void                dexter_sampler_data_copy            (DexterSampler *sampler,
                                                         gpointer dest_data,
                                                         gconstpointer source_data);
void                dexter_sampler_data_free            (DexterSampler *sampler,
                                                         gpointer data);
gpointer            dexter_sampler_input_new            (DexterSampler *sampler);
void                dexter_sampler_input_free           (DexterSampler *sampler,
                                                         gpointer input);

Description

Samplers are Libdexter objects that are capable of sampling data in some meaningful domain, storing the data internally and returning the data to the caller. Each sampler "service" is implemented in a Libdexter plug-in and has a universally unique identifier (uuid) to distinguish it from all other Libdexter services. Libdexter provides the framework for implementing these plug-in services, instantiating them within your application and running them remotely over the network.

In order to instantiate sampler objects, a service broker must first be used to obtain a list of available services from your local process or from a remote host. You then select a desired service from the list and specify it in dexter_sampler_new() to create the sampler. Once created, you may then take data "snapshots" with dexter_sampler_sample(), and copy and/or duplicate the sampler data, e.g. with dexter_sampler_data_copy(), etc.

Callbacks can be used to receive asynchronous notifications of data changes in the sampler after dexter_sampler_sample() is called. To use callbacks, create a null-terminated array of DexterSamplerDataCallback's and specify that array to dexter_sampler_new(). You can free the callback array immediately since the sampler creates a private copy. Callbacks are each invoked with a private copy of the sampler's data, rather than chaining the same memory to each callback. The data copy is freed by Libdexter automatically when the callback returns.

If a channel is specified in dexter_sampler_new(), the returned sampler is a transparent proxy to a partner object that is created on the channel's remote host. The remote object does the actual sampling while Libdexter handles the transmission of the data back to the proxy sampler running locally in your application. There is no difference in the way local and remote samplers are used from the application's perspective.

Details

DEXTER_SAMPLER_ERROR

#define DEXTER_SAMPLER_ERROR dexter_sampler_error_quark()

The error domain of the libdexter sampler subsystem.

enum DexterSamplerError

typedef enum {
    DEXTER_SAMPLER_ERROR_FAILED
} DexterSamplerError;

Error codes for DexterSampler operations.

DEXTER_SAMPLER_ERROR_FAILED

 generic failure.

DexterSampler

typedef struct _DexterSampler DexterSampler;

Opaque type with no public members.

DexterSamplerDataCallback ()

void                (*DexterSamplerDataCallback)        (gpointer sampler,
                                                         gpointer sampler_data);

Each sampler callback receives its own copy of the plugin-defined, sampler_data structure.

The library will free the sampler_data for you after the callback returns.

sampler :

 gpointer to sampler that originated the callback.

sampler_data :

 gpointer to plugin-defined sampler data.

dexter_sampler_new ()

DexterSampler *     dexter_sampler_new                  (const DexterPluginService *service,
                                                         const DexterSamplerDataCallback *callbacks,
                                                         DexterChannel *channel,
                                                         GError **error);

Creates a DexterSampler implementing the indicated DexterPluginService.

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 after dexter_sampler_sample() updates the sampler.

If a channel is indicated, the sampler operates transparently as a proxy to a 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 sampler operates locally (in-process).

The sampler must be freed when done with dexter_sampler_free().

service :

 a DexterPluginService.

callbacks :

 optional, null-terminated array of DexterSamplerDataCallback functions, or NULL.

channel :

 optional DexterChannel over which the sampler operates, or NULL.

error :

 return location for optional GError.

Returns :

 DexterSampler if successful or NULL otherwise.

dexter_sampler_free ()

void                dexter_sampler_free                 (DexterSampler *sampler,
                                                         GError **error);

Frees a DexterSampler created with dexter_sampler_new().

If the sampler was created over a channel, the channel should be open when calling this function. A message will be 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.

sampler :

 a DexterSampler.

error :

 return location of optional GError.

dexter_sampler_initialize ()

gboolean            dexter_sampler_initialize           (DexterSampler *sampler,
                                                         const gint *param,
                                                         gconstpointer input,
                                                         GError **error);

Performs one-time initialization of the sampler created with dexter_sampler_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 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 sampler should be initialized once after creation with dexter_sampler_new() and before sampling with dexter_sampler_sample().

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

sampler :

 a DexterSampler.

param :

 address of an optional gint parameter, or NULL.

input :

 optional gconstpointer to sampler-specific initialization data, or NULL.

error :

 return location of optional GError.

Returns :

 gboolean indicating success or failure;

dexter_sampler_sample ()

gboolean            dexter_sampler_sample               (DexterSampler *sampler,
                                                         GError **error);

Have the sampler refresh its data sample.

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

sampler :

 a DexterSampler.

error :

 return location for an optional GError.

Returns :

 gboolean indicating success or failure.

dexter_sampler_data_new ()

gpointer            dexter_sampler_data_new             (DexterSampler *sampler,
                                                         gboolean populate);

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

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

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

sampler :

 a DexterSampler.

populate :

 gboolean to determine if returned memory is populated with current sampler data or zero-filled.

Returns :

 gpointer to newly allocated sample memory.

dexter_sampler_data_dup ()

gpointer            dexter_sampler_data_dup             (DexterSampler *sampler,
                                                         gconstpointer source_data);

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

The user must free this memory with dexter_sampler_data_free().

sampler :

 a DexterSampler.

source_data :

 gconstpointer to sample data to duplicate.

Returns :

 gpointer to newly allocated memory containing the duplicated data.

dexter_sampler_data_xfer ()

void                dexter_sampler_data_xfer            (DexterSampler *sampler,
                                                         gpointer old_data,
                                                         gconstpointer new_data);

Transfers (copies) data into and/or out of the sampler. If old_data is indicated, the 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 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 sampler data is with dexter_sampler_sample(), i.e. simply take a new sample.

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

/* One way to get the sampler's current data. */
gpointer current_data = dexter_sampler_data_new (sampler, TRUE);
 
/* Another way */
gpointer current_data = dexter_sampler_data_new (sampler, FALSE);
dexter_sampler_data_xfer (sampler, current_data, NULL);

sampler :

 a DexterSampler.

old_data :

 optional gpointer to memory to receive a copy of the sampler's current (old) data, or NULL.

new_data :

 optional gconstpointer to memory to replace the sampler's current data, or NULL.

dexter_sampler_data_copy ()

void                dexter_sampler_data_copy            (DexterSampler *sampler,
                                                         gpointer dest_data,
                                                         gconstpointer source_data);

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

sampler :

 a DexterSampler.

dest_data :

 gpointer to destination memory to receive the copy.

source_data :

 gconstpointer to source memory for the copy.

dexter_sampler_data_free ()

void                dexter_sampler_data_free            (DexterSampler *sampler,
                                                         gpointer data);

Frees sampler data previously allocated with dexter_sampler_data_new() or dexter_sampler_data_dup().

sampler :

 a DexterSampler.

data :

 gpointer to sampler data to free.

dexter_sampler_input_new ()

gpointer            dexter_sampler_input_new            (DexterSampler *sampler);

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

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

sampler :

 a DexterSampler.

Returns :

 gpointer to newly allocated input structure.

dexter_sampler_input_free ()

void                dexter_sampler_input_free           (DexterSampler *sampler,
                                                         gpointer input);

Frees an input structure previously allocated with dexter_sampler_input_new().

sampler :

 a DexterSampler.

input :

 gpointer to sampler input to free.
Generated by GTK-Doc V1.18