![]() |
![]() |
![]() |
libinfinity-0.3 Reference Manual | ![]() |
---|---|---|---|---|
#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_component th 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 : |