Next: , Previous: , Up: C API   [Contents][Index]


5.14 libdat

5.14.1 Overview

View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/coverage/src/lib/dat/index.html.

5.14.2 API

Function: lw6dat_miss_t * lw6dat_miss_new (lw6sys_context_t * sys_context, u_int64_t from_id, int serial_min, int serial_max)

from_id: who needs to resend the message

serial_min: serial range begin (included)

serial_max: serial range end (included)

Creates a miss structure, simply allocates memory and pumps values into the right fields.

Return value: new dynamically allocated object

Function: void lw6dat_miss_free (lw6sys_context_t * sys_context, lw6dat_miss_t * miss)

miss: structure to free

Frees a miss structure, simply unallocates memory.

Return value: none.

Function: void lw6dat_miss_sync (lw6sys_context_t * sys_context, lw6dat_miss_t * dst, lw6dat_miss_t * src)

dst: target object

src: source object

Writes the contents of src to dst

Return value: none.

Function: int lw6dat_miss_is_same (lw6sys_context_t * sys_context, lw6dat_miss_t * a, lw6dat_miss_t * b)

a: first element to compare

b: second element to compare

Compares two miss objects, returning true if they are the same.

Return value: 1 if same, else 0.

Function: int lw6dat_miss_is_included (lw6sys_context_t * sys_context, lw6dat_miss_t * a, lw6dat_miss_t * b)

a: first element to compare

b: second element to compare

Compares two miss objects, returning true if a is included in b.

Return value: 1 if included, else 0.

Function: int lw6dat_miss_overlaps (lw6sys_context_t * sys_context, lw6dat_miss_t * a, lw6dat_miss_t * b)

a: first element to compare

b: second element to compare

Compares two miss objects, returning true if a overlaps with b.

Return value: 1 if included, else 0.

Function: int lw6dat_test_register (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

mode: test mode (bitmask)

Registers all tests for the libdat module.

Return value: 1 if test is successfull, 0 on error.

Function: int lw6dat_test_run (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

mode: test mode (bitmask)

Runs the dat module test suite, testing most (if not all...) functions.

Return value: 1 if test is successfull, 0 on error.

Function: int lw6dat_warehouse_init (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, u_int64_t local_node_id, int64_t seq_0)

sys_context: global system context

warehouse: object to initialize

local_node_id: id of local node, used to handle local messages

seq_0: initial seq number

Initializes a warehouse object. Won’t free anything, will just erase values if they’re here

Return value: new object, allocated dynamically

Function: lw6dat_warehouse_t * lw6dat_warehouse_new (lw6sys_context_t * sys_context, u_int64_t local_node_id, int64_t seq_0)

sys_context: global system context

local_node_id: id of local node, used to handle local messages

seq_0: initial seq number

Creates a new warehouse object.

Return value: new object, allocated dynamically

Function: void lw6dat_warehouse_free (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: the object to free

Frees a warehouse object.

Return value: new object, allocated dynamically

Function: void lw6dat_warehouse_clear (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: the object to clear

Clears a warehouse object. Clears means emptying everything and resetting the current seq_id to the minimal/start value.

Return value: none.

Function: void lw6dat_warehouse_purge (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: the object to purge

Purges a warehouse object. Purges means emptying everything but keeping the current seq_id and the nodes list unchanged.

Return value: none.

Function: int lw6dat_warehouse_get_nb_nodes (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: the warehouse object to query.

Tells how many nodes are registered in the object.

Return value: integer, number of nodes

Function: u_int64_t lw6dat_warehouse_get_local_id (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: the warehouse object to query.

Returns the local id.

Return value: 64-bit id.

Function: int lw6dat_warehouse_get_local_serial (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: the warehouse object to query.

Returns the latest (highest) serial number given for local node.

Return value: integer, latest serial number

Function: int64_t lw6dat_warehouse_get_local_seq_0 (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: the warehouse object to query

Gives the warehouse seq_0 number, any seq below does not make sense.

Return value: long integer.

Function: void lw6dat_warehouse_set_local_seq_0 (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, int64_t seq_0)

sys_context: global system context

warehouse: the warehouse object to modify

seq_0: the new seq value

Set the warehouse seq_0 number, any seq below does not make sense.

Return value: none.

Function: int64_t lw6dat_warehouse_get_local_seq_last (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: the warehouse object to query

Gives the warehouse seq_last number, this is the seq that corresponds to the last local message put in this warehouse. This is usefull to get the last seq used and, for instance, put a NOP message just for keepalive purposes.

Return value: long integer.

Function: int lw6dat_warehouse_register_node (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, u_int64_t node_id, int serial_0, int64_t seq_0)

sys_context: global system context

warehouse: object to update

node_id: id of node to register

serial_0: serial number of first message

seq_0: initial seq number

Registers a node, in practice this is automatically done when receiving a data message but it might be interesting to do it elsewhere and force it.

Return value: the stack index of the registered node, <0 is invalid.

Function: int lw6dat_warehouse_is_node_registered (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, u_int64_t node_id)

sys_context: global system context

warehouse: object to update

node_id: id of node to register

Tells wether a node is registered or not in our list.

Return value: 1 if registered, 0 if not.

Function: int lw6dat_warehouse_put_atom_str (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, u_int64_t logical_from, const char * full_str)

sys_context: global system context

warehouse: warehouse object to use

logical_from: from who the message came from originally

full_str: message of the form serial i n seq from cmd

Puts an atomic string in the object, this kind of string is typically received on the network.

Return value: 1 on success, 0 on error

Function: int lw6dat_warehouse_calc_serial_draft_and_reference (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: object to work on

The various get_seq functions can perform slowly if we don’t pre-calculate the serial number of draft and reference atoms. So this calculation is not within the functions themselves but can be cached by using this function. Just call it and after you might query the object for reference and draft info.

Return value: 1 if some valid informations were found, else 0, which means no interesting (complete) atoms where found, and there’s probably nothing to do yet.

Function: int lw6dat_warehouse_put_local_msg (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, const char * msg)

sys_context: global system context

warehouse: warehouse object to use

msg: message

Puts a message in the object. The message will be splitted into several atoms if needed, it can be arbitrary long.

Return value: 1 on success, 0 on error

Function: int64_t lw6dat_warehouse_get_seq_min (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: object to query

Tells the lowest seq referenced in the warehouse. Does not mean this is the lowest ever received, only we really have no chances of going below that point, nothing is stored, either complete or partial, below that.

Return value: integer.

Function: int64_t lw6dat_warehouse_get_seq_max (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: object to query

Tells the highest seq referenced in the warehouse. Does not mean an actual message can be built from it, only we’ve got some traces of such a high seq.

Return value: integer.

Function: int64_t lw6dat_warehouse_get_seq_draft (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: object to query

Tells the highest seq that can be considered as a valid draft. This is not exactly the maximimum seq encountered, for here we want at least one complete message and not just one chunk of data (an atom) referring to a high seq, we want the complete stuff. However there can be missing messages in between.

Return value: integer.

Function: int64_t lw6dat_warehouse_get_seq_reference (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: object to query

Tells the highest seq that can be considered as a reference. Being considered as a reference means we received all messages for this seq *and* at least one message from the following seq, and this for every node involved. This being said, we’re sure to have the right information, nothing is missing.

Return value: integer.

Function: lw6sys_list_t * lw6dat_warehouse_get_msg_list_by_seq (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, int64_t seq_min, int64_t seq_max, int for_reference, lw6sys_progress_t * progress)

sys_context: global system context

warehouse: object to query

seq_min: lowest sequence number (round or chat index)

seq_max: highest sequence number (round or chat index)

for_reference: set to 1 if this is for reference building else 0 for draft

progress: progress indicator (read/write).

Gets the list of messages for a given sequence (round or chat index), polling all the nodes. The from and to boundaries are included.

Return value: a list of strings.

Function: lw6sys_list_t * lw6dat_warehouse_get_atom_str_list_not_sent (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, u_int64_t logical_to)

sys_context: global system context

warehouse: object to query

logical_to: the id of the node that we want to send data to

Returns all the messages that were not sent for the given warehouse.

Return value: a list of strings, containing atoms.

Function: lw6sys_list_t * lw6dat_warehouse_get_miss_list (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, int max_range, lw6sys_progress_t * progress)

sys_context: global system context

warehouse: object to query

max_range: max range of the returned list (-1 if none)

progress: progress indicator, to show advancement to end-user

Returns a list of lw6dat_miss_t objects which contains informations about the messages which need to be re-sent by peers. The function will always return something, the list is not cleared if it’s called several times, so one should not poll this too often. Additionnally, the max_range parameter can be used to limit the size of the returned ranges, to avoid querying for too many messages at once.

Return value: a list of pointers to lw6dat_miss_t structs, NULL on failure.

Function: void lw6dat_warehouse_miss_invalidate (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, u_int64_t from_id, u_int64_t to_id, int serial_min, int serial_max)

sys_context: global system context

warehouse: object to modify

from_id: node which needs to resend data

to_id: node which needs to get the data

serial_min: minimum serial number to send

serial_max: maximum serial number to send

Re-sends messages in a given serial range. Actually, does not really resend messages, but marks them as needing to be sent again. We might, or not, have those messages in stock, if we have them we send them, if not we just do nothing, someone else might have them.

Return value: none

Function: void lw6dat_warehouse_update_serial_miss_max (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, u_int64_t remote_id, int serial)

sys_context: global system context

warehouse: object to update

remote_id: id of remote host to update (which stack)

serial: new max serial value

Return value: none

Function: void lw6dat_warehouse_reset_nb_atom_parts_since_last_poll (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse)

sys_context: global system context

warehouse: data warehouse to reset

Resets the nb_atom_parts_since_last_poll attribute of every stack.

Return value: none

Function: int lw6dat_warehouse_get_nb_atom_parts_since_last_poll (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, u_int64_t remote_id)

sys_context: global system context

warehouse: data warehouse to get info from

remote_id: remote id to get info about

Returns the nb_atom_parts_since_last_poll attribute of the stack concerning the remote_id. The idea is to track down, since the last call to the companion reset function, how many "atom parts" have been received, by "atom part" we mean atoms representing a splitted message. Usually this corresponds to very long messages and if this number of splitted messages is large enough, we don’t send MISS commands, as it would overload the network for nothing.

Return value: number of atom parts received since last reset.

Function: int lw6dat_warehouse_meta_put (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, int64_t seq)

sys_context: global system context

warehouse: data warehouse to put message into

seq: seq to use to stamp the message

Puts a META message in the warehouse. The META message purpose is to tell other warehouses (on other nodes, peers) that the list of peers is updated. This typically happens when a node joins in.

Return value: 1 on success, 0 if failed.

Function: int lw6dat_warehouse_meta_get (lw6sys_context_t * sys_context, lw6dat_warehouse_t * warehouse, lw6msg_meta_array_t * meta_array, int64_t seq)

sys_context: global system context

warehouse: data warehouse to put message into

meta_array: current informations sendable by a meta message

seq: seq to use to stamp the message

Gets the data required for a META message. Note that this function can be called in other contexts to know who is registered within the warehouse, which, as an opaque type, doesn’t export that info otherwise.

Return value: 1 on success, 0 if failed.

Struct: lw6dat_miss_s

Used to get informations about "what messages are missing", The struct typically contains informations to send a MISS message on the network, that is, who needs to resend the information, and the message serial range. The informations "who needs it" need not be stored as this is logically our local node.

Member of lw6dat_miss_s: from_id

Type: u_int64_t

Definition: u_int64_t lw6dat_miss_s::from_id

Id of node which needs to resend the information.

Member of lw6dat_miss_s: serial_min

Type: int

Definition: int lw6dat_miss_s::serial_min

Minimum serial, included in the range.

Member of lw6dat_miss_s: serial_max

Type: int

Definition: int lw6dat_miss_s::serial_max

Maximum serial, included in the range.

Struct: lw6dat_warehouse_s

Contains all recent messages sent to peers, and received from them, int fact this is a local database, think of it as a giant array, containing all messages. This is usefull both resend messages if one peer wants one and also to check wether informations are consistent and nobody is cheating. This structure is hiddent, casted to the real stuff internally if needed, so that other parts of the code don’t rely on specific implementation.

Member of lw6dat_warehouse_s: dummy

Type: int

Definition: int lw6dat_warehouse_s::dummy

Dummy field, unused.


Next: , Previous: , Up: C API   [Contents][Index]