libdat - Liquid War 6
Description: Liquid War 6

Next: libdef, Previous: libcnx, Up: C API

### 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 (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 (lw6dat_miss_t * miss)

> miss: structure to free

> Frees a miss structure, simply unallocates memory.

> Return value: none.

— Function: void lw6dat_miss_sync (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 (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 (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 (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 (int mode)

> 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 (int mode)

> 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 (lw6dat_warehouse_t * warehouse, u_int64_t local_node_id, int64_t seq_0)

> 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 (u_int64_t local_node_id, int64_t seq_0)

> 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 (lw6dat_warehouse_t * warehouse)

> warehouse: the object to free

> Frees a warehouse object.

> Return value: new object, allocated dynamically

— Function: void lw6dat_warehouse_clear (lw6dat_warehouse_t * warehouse)

> 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 (lw6dat_warehouse_t * warehouse)

> 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 (lw6dat_warehouse_t * warehouse)

> 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 (lw6dat_warehouse_t * warehouse)

> warehouse: the warehouse object to query.

> Returns the local id.

> Return value: 64-bit id.

— Function: int lw6dat_warehouse_get_local_serial (lw6dat_warehouse_t * warehouse)

> 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 (lw6dat_warehouse_t * warehouse)

> 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 (lw6dat_warehouse_t * warehouse, int64_t seq_0)

> 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 (lw6dat_warehouse_t * warehouse)

> 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 (lw6dat_warehouse_t * warehouse, u_int64_t node_id, int serial_0, int64_t seq_0)

> 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 (lw6dat_warehouse_t * warehouse, u_int64_t node_id)

> 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 (lw6dat_warehouse_t * warehouse, u_int64_t logical_from, const char * full_str)

> 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 (lw6dat_warehouse_t * warehouse)

> 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 (lw6dat_warehouse_t * warehouse, const char * msg)

> 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 (lw6dat_warehouse_t * warehouse)

> 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 (lw6dat_warehouse_t * warehouse)

> 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 (lw6dat_warehouse_t * warehouse)

> 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 (lw6dat_warehouse_t * warehouse)

> 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 (lw6dat_warehouse_t * warehouse, int64_t seq_min, int64_t seq_max, int for_reference, lw6sys_progress_t * progress)

> 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 (lw6dat_warehouse_t * warehouse, u_int64_t logical_to)

> 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 (lw6dat_warehouse_t * warehouse, int max_range, lw6sys_progress_t * progress)

> 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 (lw6dat_warehouse_t * warehouse, u_int64_t from_id, u_int64_t to_id, int serial_min, int serial_max)

> 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 (lw6dat_warehouse_t * warehouse, u_int64_t remote_id, int serial)

> 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 (lw6dat_warehouse_t * warehouse)

> 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 (lw6dat_warehouse_t * warehouse, u_int64_t remote_id)

> 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 (lw6dat_warehouse_t * warehouse, int64_t seq)

> 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 (lw6dat_warehouse_t * warehouse, lw6msg_meta_array_t * meta_array, int64_t seq)

> 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.