| libinfinity-0.4 Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | ||||
#include <libinfinity/adopted/inf-adopted-state-vector.h>
InfAdoptedStateVector;
enum InfAdoptedStateVectorError;
void (*InfAdoptedStateVectorForeachFunc) (guint id,
guint value,
gpointer user_data);
GQuark inf_adopted_state_vector_error_quark
(void);
InfAdoptedStateVector * inf_adopted_state_vector_new (void);
InfAdoptedStateVector * inf_adopted_state_vector_copy (InfAdoptedStateVector *vec);
void inf_adopted_state_vector_free (InfAdoptedStateVector *vec);
guint inf_adopted_state_vector_get (InfAdoptedStateVector *vec,
guint id);
void inf_adopted_state_vector_set (InfAdoptedStateVector *vec,
guint id,
guint value);
void inf_adopted_state_vector_add (InfAdoptedStateVector *vec,
guint id,
gint value);
void inf_adopted_state_vector_foreach (InfAdoptedStateVector *vec,
InfAdoptedStateVectorForeachFunc func,
gpointer user_data);
int inf_adopted_state_vector_compare (InfAdoptedStateVector *first,
InfAdoptedStateVector *second);
gboolean inf_adopted_state_vector_causally_before
(InfAdoptedStateVector *first,
InfAdoptedStateVector *second);
gboolean inf_adopted_state_vector_causally_before_inc
(InfAdoptedStateVector *first,
InfAdoptedStateVector *second,
guint inc_component);
guint inf_adopted_state_vector_vdiff (InfAdoptedStateVector *first,
InfAdoptedStateVector *second);
gchar * inf_adopted_state_vector_to_string (InfAdoptedStateVector *vec);
InfAdoptedStateVector * inf_adopted_state_vector_from_string
(const gchar *str,
GError **error);
gchar * inf_adopted_state_vector_to_string_diff
(InfAdoptedStateVector *vec,
InfAdoptedStateVector *orig);
InfAdoptedStateVector * inf_adopted_state_vector_from_string_diff
(const gchar *str,
InfAdoptedStateVector *orig,
GError **error);
The InfAdoptedStateVector represents a state in the current state space. It basically maps user IDs to operation counts and states how many operations of the corresponding user have already been performed.
typedef struct _InfAdoptedStateVector InfAdoptedStateVector;
InfAdoptedStateVector is an opaque data type. You should only access it via the public API functions.
typedef enum _InfAdoptedStateVectorError {
INF_ADOPTED_STATE_VECTOR_BAD_FORMAT,
INF_ADOPTED_STATE_VECTOR_FAILED
} InfAdoptedStateVectorError;
Error codes for InfAdoptedStateVector.
A string representation of an
InfAdoptedStateVector as required by
inf_adopted_state_vector_from_string() or
inf_adopted_state_vector_from_string_diff() is invalid.
|
|
| No further specified error code. |
void (*InfAdoptedStateVectorForeachFunc) (guint id, guint value, gpointer user_data);
This function is called for every component in the state vector during
the invocation of inf_adopted_state_vector_foreach().
|
The ID of the entry. |
|
The value of the entry. |
|
The user data passed to inf_adopted_state_vector_foreach().
|
GQuark inf_adopted_state_vector_error_quark (void);
The domain for InfAdoptedStateVectorError errors.
Returns : |
A GQuark for that domain. |
InfAdoptedStateVector * inf_adopted_state_vector_new (void);
Returns a new state vector with all components set to zero.
Returns : |
A new InfAdoptedStateVector. |
InfAdoptedStateVector * inf_adopted_state_vector_copy (InfAdoptedStateVector *vec);
Returns a copy of vec.
|
The InfAdoptedStateVector to copy |
Returns : |
A copy of vec.
|
void inf_adopted_state_vector_free (InfAdoptedStateVector *vec);
Frees a state vector allocated by inf_adopted_state_vector_new() or
inf_adopted_state_vector_copy().
|
A InfAdoptedStateVector. |
guint inf_adopted_state_vector_get (InfAdoptedStateVector *vec, guint id);
Returns the timestamp for the given component. Implicitely, all IDs that the vector does not contain are assigned the timestamp 0.
|
A InfAdoptedStateVector. |
|
The component whose timestamp to look for. |
Returns : |
The component'th entry in the vector.
|
void inf_adopted_state_vector_set (InfAdoptedStateVector *vec, guint id, guint value);
Sets the given component of vec to value.
|
A InfAdoptedStateVector. |
|
The component to change. |
|
The value to set the component to. |
void inf_adopted_state_vector_add (InfAdoptedStateVector *vec, guint id, gint value);
Adds value to the current value of component. value may be negative in
which case the current value is actually decreased. Make sure to not drop
below zero this way.
|
A InfAdoptedStateVector. |
|
The component to change. |
|
The value by which to change the component. |
void inf_adopted_state_vector_foreach (InfAdoptedStateVector *vec, InfAdoptedStateVectorForeachFunc func, gpointer user_data);
Calls func for each component in vec. Note that there may be users for
which func will not be called if their timestamp is 0.
|
A InfAdoptedStateVector. |
|
The function to call. |
|
Additional data to pass to func.
|
int inf_adopted_state_vector_compare (InfAdoptedStateVector *first, InfAdoptedStateVector *second);
Performs a comparison suited for strict-weak ordering so that state vectors
can be sorted. This function returns -1 if first compares before second,
0 if they compare equal and 1 if first compares after second.
|
A InfAdoptedStateVector. |
|
Another InfAdoptedStateVector. |
Returns : |
-1, 0 or 1. |
gboolean inf_adopted_state_vector_causally_before (InfAdoptedStateVector *first, InfAdoptedStateVector *second);
Checks whether an event that occured at time second is causally
dependant on an event that occured at time first, that is all
components of first are less or equal to the corresponding component in
second.
|
A InfAdoptedStateVector. |
|
Another InfAdoptedStateVector. |
Returns : |
Whether second depends on first.
|
gboolean inf_adopted_state_vector_causally_before_inc (InfAdoptedStateVector *first, InfAdoptedStateVector *second, guint inc_component);
This function does the equivalent of
inf_adopted_state_vector_add(first, inc_component, 1); gboolean result = inf_adopted_state_vector_causally_before(first, second); inf_adopted_state_vector_add(first, inc_component, -1); return result;
But it is more efficient.
|
A InfAdoptedStateVector. |
|
Another InfAdoptedStateVector. |
|
The component to increment before comparing. |
Returns : |
Whether second depends on first with the
inc_componentth component increased by one.
|
guint inf_adopted_state_vector_vdiff (InfAdoptedStateVector *first, InfAdoptedStateVector *second);
This function returns the sum of the differences between each component
of first and second. This function can only be called if
inf_adopted_state_vector_causally_before() returns TRUE.
|
A InfAdoptedStateVector. |
|
Another InfAdoptedStateVector. |
Returns : |
The sum of the differences between each component of first and
second.
|
gchar * inf_adopted_state_vector_to_string (InfAdoptedStateVector *vec);
Returns a string representation of vec.
|
A InfAdoptedStateVector. |
Returns : |
A newly-allocated string to be freed by the caller. |
InfAdoptedStateVector * inf_adopted_state_vector_from_string (const gchar *str, GError **error);
Recreates the InfAdoptedStateVector from its string representation. If
an error occurs, the function returns NULL and error is set.
|
A string representation of a InfAdoptedStateVector. |
|
Location to place an error, if any. |
Returns : |
A new InfAdoptedStateVector, or NULL.
|
gchar * inf_adopted_state_vector_to_string_diff (InfAdoptedStateVector *vec, InfAdoptedStateVector *orig);
Returns the string representation of a diff between orig and vec. This
is possibly smaller than the representation created by
inf_adopted_state_vector_to_string(), but the same orig vector is needed
to recreate vec from the string representation. Additionally,
inf_adopted_state_vector_causally_before(orig, vec) must hold.
|
A InfAdoptedStateVector. |
|
Another InfAdoptedStateVector. |
Returns : |
A newly allocated string to be freed by the caller. |
InfAdoptedStateVector * inf_adopted_state_vector_from_string_diff (const gchar *str, InfAdoptedStateVector *orig, GError **error);
Recreates a vector from its string representation diff and the original
vector. If an error returns, the function returns NULL and error is set.
|
A string representation of a diff between state vectors. |
|
The state vector used to create str in
inf_adopted_state_vector_to_string_diff().
|
|
Location to place an error, if any. |
Returns : |
The created state vector, or NULL on error. Free with
inf_adopted_state_vector_free() when no longer needed.
|