Reference

sg_free_stats_buf(3)

statgrab vector management

NAME

sg_vector_create, sg_vector_clear, sg_vector_resize, sg_vector_free, sg_vector_clone, sg_vector_clone_into, sg_vector_compute_diff, sg_prove_vector, sg_get_nelements, sg_free_stats_buf - statgrab vector management

SYNOPSIS

FC#include "statgrab.h"
#include "vector.h"F[0]

FCstruct sg_vector *sg_vector_createF[0] FC(size_t block_size, size_t alloc_count, size_t initial_used, const sg_vector_init_info * const info);F[0]

FCvoid sg_vector_clearF[0] FC(struct sg_vector *vector);F[0]

FCstruct sg_vector *sg_vector_resizeF[0] FC(struct sg_vector *vector);F[0]

FCvoid sg_vector_freeF[0] FC(struct sg_vector *vector);F[0]

FCstruct sg_vector *sg_vector_cloneF[0] FC(const struct sg_vector *src);F[0]

FCsg_error sg_vector_clone_intoF[0] FC(struct sg_vector **dest, const struct sg_vector *src);F[0]

FCsg_error sg_vector_compute_diffF[0] FC(struct sg_vector **dest, const struct sg_vector *cur_vector, const struct sg_vector *last_vector);F[0]

FCsg_error sg_prove_vectorF[0] FC(const struct sg_vector *vec);F[0]

FCsize_t sg_get_nelementsF[0] FC(const void *data);F[0]

FCsg_error sg_free_stats_bufF[0] FC(void *data);F[0]

DESCRIPTION

FCsg_vector_createF[0]() allocates and initialises a new statgrab vector with FCinitial_usedF[0] elements ready for use. Space for FCalloc_countF[0] elements is initially allocated (to avoid too many calls to FCreallocF[0]() during later FCsg_vector_resizeF[0]() calls). The value of FCblock_sizeF[0] must be a power of 2, it's rounded up to the next power of 2 when it's not. If FCalloc_countF[0] is not a multiple of FCblock_sizeF[0], it's rounded up to the next multiple of FCblock_sizeF[0]. It returns a pointer to the newly created vector.

FCsg_vector_clearF[0]() destroys all elements contained in the given vector. In opposite to FCsg_vector_resizeF[0]( x, 0 ) the allocated size of the vector remains untouched.

FCsg_vector_resizeF[0]() increases or decreases the amount of allocated elements in the specified vector. The amount of allocated elements is always a multiple of the initialisation parameter FCblock_sizeF[0]. In the special case, FCsg_vector_resizeF[0]() is called with 0 in argument FCnew_countF[0], the vector is freed after all vector elements had been destroyed. It returns the pointer to the resized vector.

FCsg_vector_freeF[0]() destroys all vector elements and deallocates the storage belonging to the given vector.

FCsg_vector_cloneF[0]() clones all elements of the given vector into a new vector created with the same specification as the referenced one. It returns a pointer to the cloned vector.

FCsg_vector_clone_intoF[0]() clones all elements of the given source vector into the given target vector. The target vector must be created for the same element data type as the source vector. It returns an error code != to SG_ERROR_NONE if something went wrong.

FCsg_vector_compute_diffF[0]() computes a difference vector between the vector containing current statistics and another vector containing older statistics. If an element exists in the current vector but not in the opposite one, it's cloned into the result vector. If an element exists only in the opposite vector, it doesn't appear in the target vector. FCsg_vector_compute_diffF[0]() returns an error code != to SG_ERROR_NONE if something went wrong.

FCsg_prove_vectorF[0]() proves whether a pointer to a vector really points to a vector. In case the given vector pointer points to corrupted data, the program is aborted. When FCsg_prove_vectorF[0]() returns, it returns SG_ERROR_NONE.

FCsg_get_nelementsF[0]() returns the number of elements the given data area, encompasses by a statgrab vector, contains. The vector head is internally calculated from the given pointer to the first vector element.

FCsg_free_stats_bufF[0]() frees the vector emcompassing the given data area.

NOTES

Except FCsg_get_nelementsF[0]() and FCsg_free_stats_bufF[0]() none of above functions can be called from outside of the libstatgrab sources. The documented structures and APIs may change without warning. The description of all other API is intended to be read from libstatgrab developers only.

Each vector is created from two elements: the vector information and the list of elements:

FC
template <class T, class Impl>
struct sg_vector {
        size_t used_count;
        size_t alloc_count;
        size_t block_shift;
        Impl vector_implementation;
        T elements[alloc_count];
};
      F[0]

Of course, it is not valid C, so being tricky was the solution:

FC
typedef struct sg_vector {
	size_t used_count;
	size_t alloc_count;
	size_t block_shift;
	struct sg_vector_init_info info;
} sg_vector;
struct sg_vector_size_helper {
	struct sg_vector v;
	long long ll;
};
#define VECTOR_SIZE offsetof(struct sg_vector_size_helper,ll)
/* Return the data ptr of a vector */
#define VECTOR_DATA(vector) \
	(vector ? (void *)(((char *)vector)+VECTOR_SIZE) : NULL)
#define VECTOR_ADDR_ARITH(ptr) \
	(sg_vector *)(((char *)(ptr))-VECTOR_SIZE)
/* Return the vector for a data */
#define VECTOR_ADDRESS(ptr) \
	((ptr) ? (SG_ERROR_NONE == sg_prove_vector(VECTOR_ADDR_ARITH(ptr)) ? VECTOR_ADDR_ARITH(ptr) : NULL ) : NULL)
      F[0]

This also allows user functions as FCsg_get_nelementsF[0]() and FCsg_free_stats_bufF[0]() to switch easily between the vector structure and the content.

THE VECTOR SPECIALISATION STRUCTURE

As mentioned, the vector implementation uses strategies from the object oriented programming concept named "polymorphism". A vector is described by a small object containing inherent attributes like element size and a bunch of "virtual methods" to do element related tasks like initialising or destroying elements.

FC
typedef void (*vector_init_function)(void *item);
typedef sg_error (*vector_copy_function)(const void *src, void *dst);
typedef sg_error (*vector_compute_diff_function)(void *dst, const void *src);
typedef int (*vector_compare_function)(const void *a, const void *b);
typedef void (*vector_destroy_function)(void *item);
struct sg_vector_init_info {
        size_t item_size;
        vector_init_function init_fn;
        vector_copy_function copy_fn;
        vector_compute_diff_function compute_diff_fn;
        vector_compare_function compare_fn;
        vector_destroy_function destroy_fn;
};
      F[0]

The instances of struct FCsg_vector_init_infoF[0] are conceptional statically initialised by using either the preprocessor macro FCVECTOR_INIT_INFO_FULL_INITF[0](FCtypeF[0]) or FCVECTOR_INIT_INFO_EMPTY_INITF[0](FCtypeF[0]). Here're some examples to demonstrate how it's meant:

Initialising CPU statistics vector description

FC
VECTOR_INIT_INFO_EMPTY_INIT(sg_cpu_stats);
          F[0]

Initialising Host-Info statistics vector description

FC
static void sg_os_stats_item_init(sg_os_stats *d);
static void sg_os_stats_item_destroy(sg_os_stats *d);
#define sg_os_stats_item_copy NULL
#define sg_os_stats_item_compute_diff NULL
#define sg_os_stats_item_compare NULL
VECTOR_INIT_INFO_FULL_INIT(sg_os_stats);
          F[0]

Initialising Disk-IO statistics vector description

FC
static void sg_disk_io_stats_item_init(sg_disk_io_stats *d);
static sg_error sg_disk_io_stats_item_copy(sg_disk_io_stats *d, const sg_disk_io_stats *s);
static sg_error sg_disk_io_stats_item_compute_diff(const sg_disk_io_stats *s, sg_disk_io_stats *d);
static int sg_disk_io_stats_item_compare(const sg_disk_io_stats *a, const sg_disk_io_stats *b);
static void sg_disk_io_stats_item_destroy(sg_disk_io_stats *d);
VECTOR_INIT_INFO_FULL_INIT(sg_disk_io_stats);
          F[0]

WORKING WITH VECTORS

To simplify the working with the vector management functions, some preprocessor macros are available. They are shown here as if they were functions to ease understanding.

FCstruct sg_vector *VECTOR_CREATEF[0] FC(identifier type, size_t block_size);F[0]

FCvoid VECTOR_CLEARF[0] FC(struct sg_vector *vector);F[0]

FCstruct sg_vector *VECTOR_CREATE_OR_RESIZEF[0] FC(struct sg_vector *vector, size_t new_count, identifier type);F[0]

FCvoid VECTOR_UPDATEF[0] FC(struct sg_vector **vectorptr, size_t new_count, datatype *data, identifier datatype);F[0]

FCvoid VECTOR_ITEM_COUNTF[0] FC(struct sg_vector *vector);F[0]

FCVECTOR_CREATEF[0]() calls FCsg_vector_createF[0]() with FCalloc_count = block_sizeF[0] and FCinitial_used = 0F[0] using the vector specialisation FCtype##_vector_init_infoF[0].

FCVECTOR_CLEARF[0]() simply calls FCsg_vector_clearF[0](). This macro exists only for conformity.

FCVECTOR_CREATE_OR_RESIZEF[0]() calls FCsg_vector_createF[0]() when the given vector pointer points to FCNULLF[0] or FCsg_vector_resizeF[0]() otherwise. The result of the appropriate function is returned.

FCVECTOR_UPDATEF[0]() calls FCVECTOR_CREATE_OR_RESIZEF[0]() and sets data to the first element of the resulting vector when a non-NULL pointer got, to NULL otherwise. When FCVECTOR_CREATE_OR_RESIZEF[0]() returns a NULL pointer and FCnew_countF[0] is not equal to 0 (zero), the instructions from the macro FCVECTOR_UPDATE_ERROR_CLEANUPF[0] are executed to cleanup before returning from current subroutine with the error which has been occurred.

FCVECTOR_ITEM_COUNTF[0]() returns 0 for a non-existing vector (FCvectorF[0] == 0) and the number of containing elements otherwise.

RETURN VALUES

Beside error codes, the return values, if any, are always a pointer to vector structures (struct FCsg_vectorF[0] *).

SEE ALSO

statgrab(3)

WEBSITE

⟨https://libstatgrab.org/⟩

History