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

### 5.14 libdat

#### 5.14.1 Overview

View lcov test coverage results on http://www.gnu.org/software/liquidwar6/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: 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.

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