Container: A Service to manage Jazz blocks. All Jazz blocks are managed by this or a descendant of this. More...

#include <container.h>

Inheritance diagram for jazz_elements::Container:

Public Member Functions
	Container (pLogger a_logger, pConfigFile a_config)

StatusCode	start ()

StatusCode	shut_down ()

void	enter_read (pTransaction p_txn)

void	enter_write (pTransaction p_txn)

void	leave_read (pTransaction p_txn)

void	leave_write (pTransaction p_txn)

StatusCode	new_block (pTransaction &p_txn, int cell_type, int dim, int fill_tensor=FILL_NEW_DONT_FILL, int stringbuff_size=0, const char p_text=nullptr, char eol='\n', AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, int num_items, StaticBlockHeader p_hea[], Name p_names[], pBlock p_block[], AttributeMap dims=nullptr, AttributeMap att=nullptr)

StatusCode	new_block (pTransaction &p_txn, pBlock p_from, pBlock p_row_filter, AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, pTuple p_from, pChar name, AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, pBlock p_from_text, int cell_type, pKind p_as_kind=nullptr, AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, pBlock p_from_raw, pChar p_fmt=nullptr, bool ret_as_string=false, AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, int cell_type)

StatusCode	new_block (pTransaction &p_txn, Index &index)

virtual StatusCode	new_transaction (pTransaction &p_txn)

virtual void	destroy_transaction (pTransaction &p_txn)

virtual StatusCode	get (pTransaction &p_txn, pChar p_what)

virtual StatusCode	get (pTransaction &p_txn, pChar p_what, pBlock p_row_filter)

virtual StatusCode	get (pTransaction &p_txn, pChar p_what, pChar name)

virtual StatusCode	locate (Locator &location, pChar p_what)

virtual StatusCode	header (StaticBlockHeader &hea, pChar p_what)

virtual StatusCode	header (pTransaction &p_txn, pChar p_what)

virtual StatusCode	put (pChar p_where, pBlock p_block, int mode=WRITE_AS_BASE_DEFAULT)

virtual StatusCode	new_entity (pChar p_where)

virtual StatusCode	remove (pChar p_where)

virtual StatusCode	copy (pChar p_where, pChar p_what)

virtual StatusCode	exec (pTransaction &p_txn, Locator &function, pTuple p_args)

virtual StatusCode	modify (Locator &function, pTuple p_args)

virtual StatusCode	as_locator (Locator &result, pChar p_what)

virtual StatusCode	get (pTransaction &p_txn, Locator &what)

virtual StatusCode	get (pTransaction &p_txn, Locator &what, pBlock p_row_filter)

virtual StatusCode	get (pTransaction &p_txn, Locator &what, pChar name)

virtual StatusCode	locate (Locator &location, Locator &what)

virtual StatusCode	header (StaticBlockHeader &hea, Locator &what)

virtual StatusCode	header (pTransaction &p_txn, Locator &what)

virtual StatusCode	put (Locator &where, pBlock p_block, int mode=WRITE_AS_BASE_DEFAULT)

virtual StatusCode	new_entity (Locator &where)

virtual StatusCode	remove (Locator &where)

virtual StatusCode	copy (Locator &where, Locator &what)

StatusCode	unwrap_received (pTransaction &p_txn)

StatusCode	unwrap_received (pTransaction &p_txn, pBlock p_maybe_block, int rec_size)

void	base_names (BaseNames &base_names)

Public Member Functions inherited from jazz_elements::Service
	Service (pLogger a_logger, pConfigFile a_config)

virtual pChar const	id ()

void	log (int loglevel, const char *message)

void	log_printf (int loglevel, const char *fmt,...)

bool	get_conf_key (const char *key, int &value)

bool	get_conf_key (const char *key, double &value)

bool	get_conf_key (const char *key, std::string &value)

Protected Member Functions
void *	malloc (size_t size)

pBlock	block_malloc (size_t size)

void	lock_container ()

void	unlock_container ()

StatusCode	destroy_container ()

int	from_hex (char c)

Protected Attributes
int	max_transactions
	The configured ONE_SHOT_MAX_TRANSACTIONS.

uint64_t	warn_alloc_bytes
	Taken from ONE_SHOT_WARN_BLOCK_KBYTES.

uint64_t	fail_alloc_bytes
	Taken from ONE_SHOT_ERROR_BLOCK_KBYTES.

uint64_t	alloc_bytes
	The current allocation in bytes.

pTransaction	p_buffer
	The buffer for the transactions.

pTransaction	p_free
	The free list of transactions.

bool	alloc_warning_issued
	True if a warning was issued for over-allocation.

Lock32	_lock_
	A lock for the deque of transactions.

Private Member Functions
StatusCode	new_container ()

int	skip_space (pChar &p_in, int &num_bytes)

char	get_char (pChar &p_in, int &num_bytes)

bool	get_item_name (pChar &p_in, int &num_bytes, pChar p_out, bool check_quotes=true, bool check_colon=true)

bool	sscanf_int32 (pChar &p_in, int &num_bytes, int &result)

bool	push_int_cell (pChar cell, pChar &p_st, int *&p_out)

bool	push_int_cell (pChar cell, pChar &p_st, long long *&p_out)

bool	push_bool_cell (pChar cell, pChar &p_st, bool *&p_out)

bool	push_bool_cell (pChar cell, pChar &p_st, uint32_t *&p_out)

bool	push_real_cell (pChar cell, pChar &p_st, float *&p_out)

bool	push_real_cell (pChar cell, pChar &p_st, double *&p_out)

bool	push_time_cell (pChar cell, pChar &p_st, time_t *&p_out, pChar fmt)

bool	get_type_and_shape (pChar &p_in, int &num_bytes, ItemHeader *item_hea, MapSI &dims)

bool	get_shape_and_size (pChar &p_in, int &num_bytes, int cell_type, ItemHeader *item_hea)

bool	fill_text_buffer (pChar &p_in, int &num_bytes, pChar p_out, int num_cells, int is_NA[], int hasLN[])

bool	fill_tensor (pChar &p_in, int &num_bytes, pBlock p_block)

int	new_text_block (pTransaction &p_txn, ItemHeader &item_hea, pChar &p_in, int &num_bytes, AttributeMap *att=nullptr)

int	tensor_int_as_text (pBlock p_block, pChar p_dest, pChar p_fmt)

int	tensor_bool_as_text (pBlock p_block, pChar p_dest)

int	tensor_float_as_text (pBlock p_block, pChar p_dest, pChar p_fmt)

int	tensor_string_as_text (pBlock p_block, pChar p_dest)

int	tensor_time_as_text (pBlock p_block, pChar p_dest, pChar p_fmt)

int	tensor_tuple_as_text (pTuple p_tuple, pChar p_dest, pChar p_fmt, int item_len[])

int	tensor_kind_as_text (pKind p_kind, pChar p_dest)

void	opening_brackets (int rank, pChar &p_ret)

pChar	as_shape (int rank, int dim[], pChar p_ret, pKind p_kind)

void	as_hex (pChar &p_dest, uint8_t bl)

void	separator (int rank_1, int dim[], int idx[], pChar &p_ret)

int	separator_len (int rank_1, int dim[], int idx[])

Private Attributes
char	HEX [16] = {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'}
	Hex chars.

Additional Inherited Members
Data Fields inherited from jazz_elements::Service
pLogger	p_log
	The logger.

pConfigFile	p_conf
	The configuration file.

Detailed Description

Container: A Service to manage Jazz blocks. All Jazz blocks are managed by this or a descendant of this.

This is the root class for all containers. It is basically an abstract class with some helpful methods but is not instanced as an object. Its descendants are: Channels, Volatile and Persisted (in jazz_elements) + anything allocating RAM, E.g., the API.

There is no class Channel (in singular), copy() is a method that copies blocks across Containers (or different media in Channels). Channels does all the block transactions across media (files, folders, shell, urls, zeroMQ pipes, Index types, ...).

Container provides a neat API for all descendants, including:

Transparent thread safety .enter_read() .enter_write() .leave_read() .leave_write() .lock_container() .unlock_container()
Allocation: .new_block(), .destroy_transaction()
Crud: .get(), .locate(), .header(), .new_entity(), .put(), .remove(), .copy()
Code execution: .exec() and .modify()
Support for container names in the API .base_names()
A configuration style for all descendants

It provides, exposed by the root Container class, but also used internally by descendants;

A transparent deque of Transaction structures

One-shot Block allocation

This is the only container providing one-shot Block allocation. This does not mean, unlike in previous versions, the caller owns the pointer. One-shot Block allocation is intended for computing intermediate blocks like: blocks generated from constants, from slicing, returned by functions, etc. In these blocks, the locator is meaningless, the caller will create it by new_block(), use it and call destroy_transaction() when done.

Instances and inheritance

Note that the descendants don't inherit each other, but they all have the basic deque mechanism inherited from Container: i.e., they can all allocate new blocks for their own purposes. Configuration-wise the allocations set by ONE_SHOT_MAX_TRANSACTIONS, ONE_SHOT_WARN_BLOCK_KBYTES, ... only apply to the instance of the class Container, the descendants use their own limits in which they include this allocation combined with whatever other allocations they do. The total allocation of the Jazz node is the sum of all (plus some small amount used by libraries, etc. that is not dependant on data size).

Container descendants

Note that Containers own their Transactions and may allocate p_route blocks including all kinds of things like session cookies or credentials for libcurl calls. Any container will reroute a destroy_transaction() call to its owner.

Scope of jazz_elements

Everything works at binary level, operations on blocks at this level are very simple, just copying, deleting, filtering a Tensor by (int or bool) indices, filtering a Tuple by item name and support every medium in the more conceivably efficient way.

Code execution

Code execution covers the methods exec (both for functions and mutators) and modify (a special logic used in channel). Code execution both runs at "lower level" (Core) to run a compiled pipe or at higher level (ModelsAPI). Everything goes through exec() both functions and mutators.

new_block()

NOTE** that new_block() has 8 forms. It is always called new_block() to emphasize that what the function does is create a new block (vs. sharing a pointer to an existing one). Therefore, the container allocates and owns it an requires a destroy_transaction() call when no longer needed. The forms cover all the supported ways to do basic operations like filtering and serializing.

new_block(): Create a Tensor from raw data specifying everything from scratch.
new_block(): Create a Kind or Tuple from arrays of StaticBlockHeader, names, and, in the case of a tuple, Tensors.
new_block(): Create a Tensor by selecting rows (filtering) from another Tensor.
new_block(): Create a Tensor by selecting an item from a Tuple.
new_block(): Create a Tensor, Kind or Tuple from a Text block kept as a Tensor of CELL_TYPE_BYTE of rank == 1.
new_block(): Create a Tensor of CELL_TYPE_BYTE of rank == 1 with a text serialization of a Tensor, Kind or Tuple.
new_block(): Create an empty Index block. It is dynamically allocated, an std:map, and is destroy_transaction()-ed like the others.
new_block(): Create a Tuple of (key:STRING[length],value:STRING[length]) with the content of an Index.

Constructor & Destructor Documentation

◆ Container()

jazz_elements::Container::Container	(	pLogger	a_logger,
		pConfigFile	a_config
	)

Initialize the Container without starting it.

Parameters

a_logger	A pointer to a Logger object.
a_config	A pointer to a ConfigFile object.

Member Function Documentation

◆ start()

StatusCode jazz_elements::Container::start ( )

virtual

Reads variables from config and sets private variables accordingly.

Returns: SERVICE_NO_ERROR on success, or some error.

Reimplemented from jazz_elements::Service.

Reimplemented in jazz_bebop::Core, jazz_elements::Persisted, jazz_elements::Volatile, jazz_models::Model, and jazz_models::ModelsAPI.

◆ shut_down()

StatusCode jazz_elements::Container::shut_down ( )

virtual

Destroys everything and zeroes allocation.

Returns: SERVICE_NO_ERROR on success, or some error.

Reimplemented from jazz_elements::Service.

Reimplemented in jazz_bebop::Core, jazz_elements::Persisted, jazz_elements::Volatile, jazz_models::Model, and jazz_models::ModelsAPI.

◆ enter_read()

void jazz_elements::Container::enter_read ( pTransaction p_txn )

Enter (soft lock) a Block for reading. Many readers are allowed simultaneously, but it is incompatible with writing.

Parameters

p_txn The address of the Block's Transaction.

NOTE: This is not used in API queries or normal Bop execution. In those cases, Blocks are immutable. This allows for mutable blocks in multithreaded algorithms like MCTS.

◆ enter_write()

void jazz_elements::Container::enter_write ( pTransaction p_txn )

Enter (hard lock) a Block for writing. No readers are allowed during writing.

Parameters

p_txn The address of the Block's Transaction.

NOTE: This is not used in API queries or normal Bop execution. In those cases, Blocks are immutable. This allows for mutable blocks in multithreaded algorithms like MCTS.

◆ leave_read()

void jazz_elements::Container::leave_read ( pTransaction p_txn )

Release the soft lock of Block after reading. This is mandatory for each enter_read() call or it may result in permanent locking.

Parameters

p_txn The address of the Block's Transaction.

NOTE: This is not used in API queries or normal Bop execution. In those cases, Blocks are immutable. This allows for mutable blocks in multithreaded algorithms like MCTS.

◆ leave_write()

void jazz_elements::Container::leave_write ( pTransaction p_txn )

Release the hard lock of Block after writing. This is mandatory for each enter_write() call or it may result in permanent locking.

Parameters

p_txn The address of the Block's Transaction.

NOTE: This is not used in API queries or normal Bop execution. In those cases, Blocks are immutable. This allows for mutable blocks in multithreaded algorithms like MCTS.

◆ new_block() [1/8]

StatusCode jazz_elements::Container::new_block	(	pTransaction &	p_txn,
		int	cell_type,
		int *	dim,
		int	fill_tensor = `FILL_NEW_DONT_FILL`,
		int	stringbuff_size = `0`,
		const char *	p_text = `nullptr`,
		char	eol = `'\n'`,
		AttributeMap *	att = `nullptr`
	)

Create a new Block (1): Create a Tensor from raw data specifying everything from scratch.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container. The caller can only use it read-only and must destroy_transaction() it when done.
cell_type	The tensor cell type in [CELL_TYPE_BYTE..CELL_TYPE_DOUBLE]
dim	This defines both the rank and the dimensions of the tensor. Note that, except for the first position a dimension of 0 and 1 is the same dim = {3, 1} is a vector of 3 elements with rank 1, exactly like {3, 0}. As a matter of convention, dim should always end with a 0 except when it is MAX_TENSOR_RANK long. For the first dimension 1 means one element and 0 means no element. Both have rank 1. The latter is the typical result of a selection where no row matches the condition. Blocks never have rank == 0 and zero-element blocks have the same rank as the block from which they were selected. When 0 rows are selected from a block of dim = {r, s, t} the resulting block is {0, s, t} with size == 0 and rank == 3. If dim == nullptr and p_text != nullptr, dim will be set to the number of lines (see eol) in p_text when cell_type == CELL_TYPE_STRING.
fill_tensor	How to fill the tensor. The options are: FILL_NEW_DONT_FILL (don't do anything with the tensor), FILL_NEW_WITH_ZERO (fill with binary zero no matter what the cell_type is), FILL_NEW_WITH_NA fill with the appropriate NA for the cell_type).
stringbuff_size	One of the possible ways to allocate space for strings is declaring this size. When this is non-zero a buffer will be allocated with this size plus whatever size is required by the strings in att. new_block() will only allocate the space and do nothing with it. The caller should assign strings with Block.set_string().
p_text	The other possible way to allocate space for strings is by declaring p_text. Imagine the content of p_text as a text file with n = size rows that will be pushed into the tensor and the string buffer. The eol character separates the cells. (cell_type == CELL_TYPE_STRING & p_text != nullptr) overrides any setting in fill_tensor. Also, either dim should be nullptr and set automatically or its resulting size must be the same as the number of lines in p_text.
eol	A single character that separates the cells in p_text and will not be pushed to the string buffer.
att	The attributes to set when creating the block. They are immutable.

NOTES: String buffer allocation should not be used to dynamically change attribute values. Attributes are immutable and should be changed only creating a new block with new = new_block(p_from = old, att = new_att). String buffer allocation should only be used for cell_type == CELL_TYPE_STRING and either with stringbuff_size or with p_text (and eol). If stringbuff_size is used, Block.set_string() should be used afterwards. If p_text is used, the tensor is already filled and Block.set_string() should not be called after that.

OWNERSHIP: Remember: the p_txn returned on success points inside the Container. Use it as read-only and don't forget to destroy_transaction() it when done.

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

◆ new_block() [2/8]

StatusCode jazz_elements::Container::new_block	(	pTransaction &	p_txn,
		int	num_items,
		StaticBlockHeader	p_hea[],
		Name	p_names[],
		pBlock	p_block[],
		AttributeMap *	dims = `nullptr`,
		AttributeMap *	att = `nullptr`
	)

Create a new Block (2): Create a Kind or Tuple from arrays of StaticBlockHeader, names, and, in the case of a tuple, Tensors.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container. The caller can only use it read-only and must destroy_transaction() it when done.
num_items	The number of items the Kind or Tuple will have.
p_hea	A vector of num_items pointers to StaticBlockHeaders defining the Kind or Tuple. The shape must be defined in "human-readable" format, i.e., what a pBlock->get_dimensions() returns (not the internal way a block stores it). When creating a Kind, negative constants must be defined in dims-> and will be used to create dimensions.
p_names	An array of num_items Name structures by which the items will go.
p_block	The data, only for tuples. It must have the same shape as p_hea but that will not be checked. Unlike p_hea this has the shape stores as a real block (but it is not used) instead of "human-readable". If it is nullptr, a Kind will be created, otherwise a Tuple will be created and just the tensor data will be copied from here.
dims	For Kinds only, the names of the dimensions. Note that p_hea must have negative values for the dimensions, just like when Kinds are built using Kind.new_kind() followed by Kind.add_item()
att	The attributes to set when creating the block. They are immutable. To change the attributes of a Block use the version of new_block() with parameter p_from.

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

◆ new_block() [3/8]

StatusCode jazz_elements::Container::new_block	(	pTransaction &	p_txn,
		pBlock	p_from,
		pBlock	p_row_filter,
		AttributeMap *	att = `nullptr`
	)

Create a new Block (3): Create a Tensor by selecting rows (filtering) from another Tensor.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container. The caller can only use it read-only and must destroy_transaction() it when done.
p_from	The block we want to filter from. The resulting block will be a subset of the rows (selection on the first dimension of the tensor). This can be either a tensor or a Tuple. In the case of a Tuple, all the tensors must have the same first dimension.
p_row_filter	The block we want to use as a filter. This is either a tensor of boolean or integer that can_filter(p_from).
att	The attributes to set when creating the block. They are immutable. To change the attributes of a Block use the version of new_block() with parameter p_from.

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

◆ new_block() [4/8]

StatusCode jazz_elements::Container::new_block	(	pTransaction &	p_txn,
		pTuple	p_from,
		pChar	name,
		AttributeMap *	att = `nullptr`
	)

Create a new Block (4): Create a Tensor by selecting an item from a Tuple.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container. The caller can only use it read-only and must destroy_transaction() it when done.
p_from	The Tuple from which the item is selected.
name	The name of the item to be selected.
att	The attributes to set when creating the block. They are immutable. To change the attributes of a Block use the version of new_block() with parameter p_from.

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

The Tuple already has a method .block() that does this, the difference is the .block() method returns a pointer inside the Tuple while this makes a copy to a new block, possibly with attributes.

◆ new_block() [5/8]

StatusCode jazz_elements::Container::new_block	(	pTransaction &	p_txn,
		pBlock	p_from_text,
		int	cell_type,
		pKind	p_as_kind = `nullptr`,
		AttributeMap *	att = `nullptr`
	)

Create a new Block (5): Create a Tensor, Kind or Tuple from a Text block kept as a Tensor of CELL_TYPE_BYTE of rank == 1 or a Tensor of CELL_TYPE_STRING of size == 1

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container. The caller can only use it read-only and must destroy_transaction() it when done.
p_from_text	The block containing a valid serialization of Tensor, Kind or Tuple.
cell_type	The expected output type.
p_as_kind	For Tuples only, the definition of the exact types of each item. The serialization contains names, but not types to make it JSON-like. E.g., "("temperature":[[20,21],[22,22]], "sensation":["cold", "mild"])" This can be skipped by passing a nullptr. In that case, the items will be guessed only as CELL_TYPE_INTEGER, CELL_TYPE_DOUBLE or CELL_TYPE_STRING. The serialization of a Kind includes types and does not use this. E.g. "{"temperature":INTEGER[num_places,2], "sensation":STRING[num_places]}"
att	The attributes to set when creating the block. They are immutable. To change the attributes of a Block use the version of new_block() with parameter p_from.

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

◆ new_block() [6/8]

StatusCode jazz_elements::Container::new_block	(	pTransaction &	p_txn,
		pBlock	p_from_raw,
		pChar	p_fmt = `nullptr`,
		bool	ret_as_string = `false`,
		AttributeMap *	att = `nullptr`
	)

Create a new Block (6): Create a Tensor of CELL_TYPE_BYTE of rank == 1 with a text serialization of a Tensor, Kind or Tuple.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container. The caller can only use it read-only and must destroy_transaction() it when done.
p_from_raw	The block to be serialized
p_fmt	An optional numerical precision format specifier. In the case of Tuples, if this is used all items with numerical tensors will use it. (This may imply converting integer to double depending on the specifier.)
ret_as_string	Return the serialization as a tensor of just one string rather than a vector of byte.
att	The attributes to set when creating the block. They are immutable. To change the attributes of a Block use the version of new_block() with parameter p_from.

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

◆ new_block() [7/8]

StatusCode jazz_elements::Container::new_block	(	pTransaction &	p_txn,
		int	cell_type
	)

Create a new Block (7): Create an empty Index block.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container. The caller can only use it read-only and must destroy_transaction() it when done.
cell_type	The type of index (a 48 bit CELL_TYPE_INDEX)

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

Unlike all the other blocks, Tensor, Kind and Tuple, this returns a header with an std::map. Therefore, it is dynamically allocated, by just using it. As such, it is not movable and cannot be used in any transactions other that Channels serializing it as a Tuple(key, value). When no longer needed, it has to be destroy_transaction()-ed just like the other Blocks created with new_block() and the Container will take care of freeing the std::map before destroying the transaction.

◆ new_block() [8/8]

StatusCode jazz_elements::Container::new_block	(	pTransaction &	p_txn,
		Index &	index
	)

Create a new Block (8): Create a Tuple of (key:STRING[length],value:STRING[length]) with the content of an Index.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container. The caller can only use it read-only and must destroy_transaction() it when done.
index	An Index we want to convert into a Tuple.

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

◆ new_transaction()

StatusCode jazz_elements::Container::new_transaction ( pTransaction & p_txn )

virtual

Allocate a Transaction to share a block via the API.

Parameters

p_txn A pointer to a valid Transaction passed by reference. On failure, it will assign nullptr to it.

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some error.

NOTE: The idea of this method being virtual is allowing descendants to use new_block() calls to create one shot blocks that can be later inserted into different structures.

Reimplemented in jazz_elements::Volatile.

◆ destroy_transaction()

void jazz_elements::Container::destroy_transaction ( pTransaction & p_txn )

virtual

Dealloc the Block in the p_tnx->p_block (if not null) and free the Transaction inside a Container.

Parameters

p_txn A pointer to a valid Transaction passed by reference. Once finished, p_txn is set to nullptr to avoid reusing.

NOTE: The idea of this method being virtual is allowing descendants to use new_block() calls to create one shot blocks that can be later inserted into different structures.

Reimplemented in jazz_elements::Volatile.

◆ get() [1/6]

StatusCode jazz_elements::Container::get	(	pTransaction &	p_txn,
		pChar	p_what
	)

virtual

"Easy" interface complete Block retrieval. This parses p_what and, on success, calls the native get() equivalent.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container.
p_what	Some string that as_locator() can parse into a Locator. E.g. //base/entity/key

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

Usage-wise, this is equivalent to a new_block() call. On success, it will return a Transaction that belongs to the Container and must be destroy_transaction()-ed when the caller is done.

Reimplemented in jazz_bebop::Core, jazz_elements::Channels, jazz_elements::Persisted, and jazz_elements::Volatile.

◆ get() [2/6]

StatusCode jazz_elements::Container::get	(	pTransaction &	p_txn,
		pChar	p_what,
		pBlock	p_row_filter
	)

virtual

"Easy" interface selection of rows in a Block retrieval. This parses p_what and, on success, calls the native get() equivalent.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container.
p_what	Some string that as_locator() can parse into a Locator. E.g. //base/entity/key
p_row_filter	The block we want to use as a filter. This is either a tensor of boolean or integer that can_filter(p_from).

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

Usage-wise, this is equivalent to a new_block() call. On success, it will return a Transaction that belongs to the Container and must be destroy_transaction()-ed when the caller is done.

Reimplemented in jazz_bebop::Core, jazz_elements::Channels, jazz_elements::Persisted, and jazz_elements::Volatile.

◆ get() [3/6]

StatusCode jazz_elements::Container::get	(	pTransaction &	p_txn,
		pChar	p_what,
		pChar	name
	)

virtual

"Easy" interface selection of a tensor in a Tuple retrieval. This parses p_what and, on success, calls the native get() equivalent.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container.
p_what	Some string that as_locator() can parse into a Locator. E.g. //base/entity/key
name	The name of the item to be selected.

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

Usage-wise, this is equivalent to a new_block() call. On success, it will return a Transaction that belongs to the Container and must be destroy_transaction()-ed when the caller is done.

Reimplemented in jazz_bebop::Core, jazz_elements::Channels, jazz_elements::Persisted, and jazz_elements::Volatile.

◆ locate() [1/2]

StatusCode jazz_elements::Container::locate	(	Locator &	location,
		pChar	p_what
	)

virtual

"Easy" interface : Locate a block by some relation that is understandable by the descendant.

Parameters

location	The solved location of the block.
p_what	A valid reference to a block. E.g. //deque/ent/~first, //tree/ent/key~parent, //queue/ent/~highest

Returns: SERVICE_NO_ERROR on success (and a valid location), or some negative value (error).

The default behaviour of this is returning the same locator that is given for most Containers. Only containers like Volatile which support block relations defined by commands will return actual //base/ent/key locators that are the result of some computation.

Reimplemented in jazz_elements::Channels, and jazz_elements::Volatile.

◆ header() [1/4]

StatusCode jazz_elements::Container::header	(	StaticBlockHeader &	hea,
		pChar	p_what
	)

virtual

"Easy" interface metadata of a Block retrieval. This parses p_what and, on success, calls the native header() equivalent.

Parameters

hea	A StaticBlockHeader structure that will receive the metadata.
p_what	Some string that as_locator() can parse into a Locator. E.g. //base/entity/key

Returns: SERVICE_NO_ERROR on success (and a valid hea), or some negative value (error).

This is a faster, not involving RAM allocation version of the other form of header. For a tensor, is will be the only thing you need, but for a Kind or a Tuple, you probably want the types of all its items and need to pass a pTransaction to hold the data.

Reimplemented in jazz_bebop::Core, jazz_elements::Channels, jazz_elements::Persisted, and jazz_elements::Volatile.

◆ header() [2/4]

StatusCode jazz_elements::Container::header	(	pTransaction &	p_txn,
		pChar	p_what
	)

virtual

"Easy" interface metadata of a Block retrieval. This parses p_what and, on success, calls the native header() equivalent.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container.
p_what	Some string that as_locator() can parse into a Locator. E.g. //base/entity/key

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

Unlike its faster form, this allocates a Block and therefore, it is equivalent to a new_block() call. On success, it will return a Transaction that belongs to the Container and must be destroy_transaction()-ed when the caller is done.

For Tensors it will allocate a block that only has the StaticBlockHeader (What you can more efficiently get from the other form.) For Kinds, the metadata of all the items is exactly the same a .get() call returns. For Tuples, it does what you expect: returning a Block with the metadata of all the items without the data.

Reimplemented in jazz_bebop::Core, jazz_elements::Channels, jazz_elements::Persisted, and jazz_elements::Volatile.

◆ put() [1/2]

StatusCode jazz_elements::Container::put	(	pChar	p_where,
		pBlock	p_block,
		int	mode = `WRITE_AS_BASE_DEFAULT`
	)

virtual

"Easy" interface for Block storing: This parses p_where and, on success, calls the native put() equivalent.

Parameters

p_where	Some string that as_locator() can parse into a Locator. E.g. //base/entity/key
p_block	A block to be stored. Notice it is a block, not a Transaction. If necessary, the Container will make a copy, write to disc, PUT it via http, etc. The container does not own the pointer in any way.
mode	Some writing restriction that should return an error if not supported. It controls overriding or writing just the data as when writing to a file.

Returns: SERVICE_NO_ERROR on success or some negative value (error).

Reimplemented in jazz_bebop::Core, jazz_elements::Channels, jazz_elements::Persisted, and jazz_elements::Volatile.

◆ new_entity() [1/2]

StatusCode jazz_elements::Container::new_entity ( pChar p_where )

virtual

"Easy" interface for creating entities: This parses p_where and, on success, calls the native new_entity() equivalent.

Parameters

p_where Some string that as_locator() can parse into a Locator. E.g. //base/entity

Returns: SERVICE_NO_ERROR on success or some negative value (error).

What an entity is, is Container and base dependent. It can be an lmdb database, a folder in a filesystem, a Volatile tree, ...

Reimplemented in jazz_bebop::Core, jazz_elements::Channels, jazz_elements::Persisted, and jazz_elements::Volatile.

◆ remove() [1/2]

StatusCode jazz_elements::Container::remove ( pChar p_where )

virtual

"Easy" interface for deleting entities and blocks: This parses p_where and, on success, calls the native header() equivalent.

Parameters

p_where Some string that as_locator() can parse into a Locator. E.g. //base/entity or //base/entity/key

Returns: SERVICE_NO_ERROR on success or some negative value (error).

What an entity is, is Container and base dependent. It can be an lmdb database, a folder in a filesystem, a Volatile tree, ...

Reimplemented in jazz_bebop::Core, jazz_elements::Channels, jazz_elements::Persisted, and jazz_elements::Volatile.

◆ copy() [1/2]

StatusCode jazz_elements::Container::copy	(	pChar	p_where,
		pChar	p_what
	)

virtual

"Easy" interface for Block copying: This parses p_what and p_where. On success, it calls the native copy() equivalent.

Parameters

p_where	Some destination that as_locator() can parse into a Locator. E.g. //base/entity/key
p_what	Some source that as_locator() can parse into a Locator. E.g. //base/entity/key

Returns: SERVICE_NO_ERROR on success or some negative value (error).

NOTE**: This does not copy blocks across Containers. A copy() call is a short way to do "get(tx, what); put(where, tx); destroy_transaction(tx);" without the Container needing to allocate Transactions and, possibly, not even blocks. To copy blocks across containers, you need channels.

Reimplemented in jazz_elements::Channels, jazz_elements::Persisted, and jazz_elements::Volatile.

◆ exec()

StatusCode jazz_elements::Container::exec	(	pTransaction &	p_txn,
		Locator &	function,
		pTuple	p_args
	)

virtual

The function call interface for exec: Execute a function or a model.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container.
function	Some description of a service. In general base/entity/key. In Channels the key must be empty and the entity is the pipeline. In Core, the key is field/snippet, In Model (via ModelAPI), model/(entry point).
p_args	A Tuple passed as argument to the call that is not modified.

Returns: SERVICE_ERROR_NOT_APPLICABLE since this method must be implemented in the Container descendants.

Usage-wise, this is equivalent to a new_block() call. On success, it will return a Transaction that belongs to the Container and must be destroy_transaction()-ed when the caller is done.

Reimplemented in jazz_bebop::Core.

◆ modify()

StatusCode jazz_elements::Container::modify	(	Locator &	function,
		pTuple	p_args
	)

virtual

The function call interface for modify: In jazz_elements, this is only implemented in Channels.

Parameters

function	Some description of a service. In general base/entity/key. In Channels the key must be empty and the entity is the pipeline.
p_args	In Channels: A Tuple with two items, "input" with the data passed to the service and "result" with the data returned. The result will be overridden in-place without any allocation.

Returns: SERVICE_ERROR_NOT_APPLICABLE since this method must be implemented in the Container descendants.

modify() is similar to exec(), but, rather than creating a new block with the result, it modifies the Tuple p_args.

Reimplemented in jazz_bebop::Core, and jazz_elements::Channels.

◆ as_locator()

StatusCode jazz_elements::Container::as_locator	(	Locator &	result,
		pChar	p_what
	)

virtual

The parser: A simple parser that does not support Locator.p_extra, but is enough for Volatile and Persisted.

Parameters

result	A Locator to contained the parsed result on success. (Undefined content on error.)
p_what	Some string to be parsed. E.g. //base/entity/key

Returns: SERVICE_NO_ERROR on success or some negative value (error).

More complex Container descendants that support URLs, credentials, cookies, etc. will override this minimalistic parser.

◆ get() [4/6]

StatusCode jazz_elements::Container::get	(	pTransaction &	p_txn,
		Locator &	what
	)

virtual

The "native" interface: This is what really does the job and must be implemented in the Container descendants.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container.
what	A valid reference to a block as a locator. E.g. //base/entity/key

Returns: SERVICE_NOT_IMPLEMENTED since this method must be implemented in the Container descendants.

NOTE**: The root Container class does not implement this.

Reimplemented in jazz_bebop::Core, jazz_elements::Persisted, jazz_elements::Persisted, jazz_elements::Volatile, and jazz_elements::Volatile.

◆ get() [5/6]

StatusCode jazz_elements::Container::get	(	pTransaction &	p_txn,
		Locator &	what,
		pBlock	p_row_filter
	)

virtual

The "native" interface: This is what really does the job and must be implemented in the Container descendants.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container.
what	A valid reference to a block as a locator. E.g. //base/entity/key
p_row_filter	The block we want to use as a filter. This is either a tensor of boolean or integer that can_filter(p_from).

Returns: SERVICE_NOT_IMPLEMENTED since this method must be implemented in the Container descendants.

NOTE**: The root Container class does not implement this.

Reimplemented in jazz_bebop::Core, jazz_elements::Persisted, jazz_elements::Persisted, jazz_elements::Volatile, and jazz_elements::Volatile.

◆ get() [6/6]

StatusCode jazz_elements::Container::get	(	pTransaction &	p_txn,
		Locator &	what,
		pChar	name
	)

virtual

The "native" interface: This is what really does the job and must be implemented in the Container descendants.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container.
what	A valid reference to a block as a locator. E.g. //base/entity/key
name	The name of the item to be selected.

Returns: SERVICE_NOT_IMPLEMENTED since this method must be implemented in the Container descendants.

NOTE**: The root Container class does not implement this.

Reimplemented in jazz_bebop::Core, jazz_elements::Persisted, jazz_elements::Persisted, jazz_elements::Volatile, and jazz_elements::Volatile.

◆ locate() [2/2]

StatusCode jazz_elements::Container::locate	(	Locator &	location,
		Locator &	what
	)

virtual

The "native" interface: The default behavior for most Container descendants that do not support commands is just copying.

Parameters

location	The solved location of the block.
what	A valid reference to a block. E.g. //deque/ent/~first, //tree/ent/key~parent, //queue/ent/~highest

Returns: SERVICE_NOT_IMPLEMENTED since this method must be implemented in the Container descendants.

NOTE: This just copies what into location. It will not verify the existence of the block. The function of locate() is to evaluate commands in Containers supporting them (E.g, Volatile). Otherwise, it is a trivial conversion from the easy into the native API.

Reimplemented in jazz_elements::Volatile, and jazz_elements::Volatile.

◆ header() [3/4]

StatusCode jazz_elements::Container::header	(	StaticBlockHeader &	hea,
		Locator &	what
	)

virtual

The "native" interface: This is what really does the job and must be implemented in the Container descendants.

Parameters

hea	A StaticBlockHeader structure that will receive the metadata.
what	Some Locator to the block. (See Node Method Reference in the documentation of the class Volatile.)

Returns: SERVICE_NOT_IMPLEMENTED since this method must be implemented in the Container descendants.

NOTE**: The root Container class does not implement this.

Reimplemented in jazz_bebop::Core, jazz_elements::Persisted, jazz_elements::Persisted, jazz_elements::Volatile, and jazz_elements::Volatile.

◆ header() [4/4]

StatusCode jazz_elements::Container::header	(	pTransaction &	p_txn,
		Locator &	what
	)

virtual

The "native" interface: This is what really does the job and must be implemented in the Container descendants.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container.
what	Some Locator to the block. (See Node Method Reference in the documentation of the class Volatile.)

Returns: SERVICE_NOT_IMPLEMENTED since this method must be implemented in the Container descendants.

NOTE**: The root Container class does not implement this.

Reimplemented in jazz_bebop::Core, jazz_elements::Persisted, jazz_elements::Persisted, jazz_elements::Volatile, and jazz_elements::Volatile.

◆ put() [2/2]

StatusCode jazz_elements::Container::put	(	Locator &	where,
		pBlock	p_block,
		int	mode = `WRITE_AS_BASE_DEFAULT`
	)

virtual

The "native" interface: This is what really does the job and must be implemented in the Container descendants.

Parameters

where	Some destination Locator to the block. (See Node Method Reference in the documentation of the class Volatile.)
p_block	The Block to be stored in Volatile. The Block hash and dated will be updated by this call!!
mode	Some writing restriction, either WRITE_ONLY_IF_EXISTS or WRITE_ONLY_IF_NOT_EXISTS. WRITE_TENSOR_DATA returns the error SERVICE_ERROR_WRONG_ARGUMENTS

Returns: SERVICE_NOT_IMPLEMENTED since this method must be implemented in the Container descendants.

NOTE**: The root Container class does not implement this.

Reimplemented in jazz_bebop::Core, jazz_elements::Persisted, jazz_elements::Volatile, jazz_elements::Volatile, and jazz_elements::Persisted.

◆ new_entity() [2/2]

StatusCode jazz_elements::Container::new_entity ( Locator & where )

virtual

The "native" interface: This is what really does the job and must be implemented in the Container descendants.

Parameters

where Some destination Locator to the block. (See Node Method Reference in the documentation of the class Volatile.)

Returns: SERVICE_NOT_IMPLEMENTED since this method must be implemented in the Container descendants.

NOTE**: The root Container class does not implement this.

Reimplemented in jazz_bebop::Core, jazz_elements::Persisted, jazz_elements::Persisted, jazz_elements::Volatile, and jazz_elements::Volatile.

◆ remove() [2/2]

StatusCode jazz_elements::Container::remove ( Locator & where )

virtual

The "native" interface: This is what really does the job and must be implemented in the Container descendants.

Parameters

where The block or entity to be removed. (See Node Method Reference in the documentation of the class Volatile.)

Returns: SERVICE_NOT_IMPLEMENTED since this method must be implemented in the Container descendants.

NOTE**: The root Container class does not implement this.

Reimplemented in jazz_bebop::Core, jazz_elements::Persisted, jazz_elements::Persisted, jazz_elements::Volatile, and jazz_elements::Volatile.

◆ copy() [2/2]

StatusCode jazz_elements::Container::copy	(	Locator &	where,
		Locator &	what
	)

virtual

The "native" interface: This is what really does the job and must be implemented in the Container descendants.

Parameters

where	The block or entity to be written. (See Node Method Reference in the documentation of the class Volatile.)
what	The block or entity to be read. (See Node Method Reference in the documentation of the class Volatile.)

Returns: SERVICE_NOT_IMPLEMENTED since this method must be implemented in the Container descendants.

NOTE**: The root Container class does not implement this.

Reimplemented in jazz_elements::Persisted, jazz_elements::Persisted, jazz_elements::Volatile, and jazz_elements::Volatile.

◆ unwrap_received() [1/2]

StatusCode jazz_elements::Container::unwrap_received ( pTransaction & p_txn )

inline

Convert a received "block" (just an array of data received) which is in an array of byte to its final form.

Parameters

p_txn An already allocated transaction with the data in an array of rank 1 of CELL_TYPE_BYTE

Returns: SERVICE_NO_ERROR except if alloc is necessary and fails, then SERVICE_ERROR_NO_MEM and destroys the p_txn.

Logic: If the content is a valid (== hash64-checked) block -> The block is replaced by the block inside else, if the content is a string (its length == the length of the block) -> The block is replaced by a CELL_TYPE_STRING else, -> it is left as it is.

◆ unwrap_received() [2/2]

StatusCode jazz_elements::Container::unwrap_received	(	pTransaction &	p_txn,
		pBlock	p_maybe_block,
		int	rec_size
	)

inline

Convert a received "block" (just an array of data received) which is just a pointer and a size to its final form.

Parameters

p_txn	A transaction to store the result created in case SERVICE_NO_ERROR is returned.
p_maybe_block	A pointer to the data received
rec_size	The size of the data received.

Returns: SERVICE_NO_ERROR except if alloc is necessary and fails, then SERVICE_ERROR_NO_MEM.

Logic: If the content is a valid (== hash64-checked) block -> Create a new transaction containing a copy of that block. else, if the content is a string (its length == the length of the block) -> New transaction with a CELL_TYPE_STRING. else, -> New transaction with a CELL_TYPE_BYTE.

◆ base_names()

void jazz_elements::Container::base_names ( BaseNames & base_names )

Add the base names for this Container.

Parameters

base_names A BaseNames map passed by reference to which the base names of this object are added by this call.

The root class Container does not add any base names.

◆ malloc()

void * jazz_elements::Container::malloc ( size_t size )

inlineprotected

An std::malloc() that increases .alloc_bytes on each call and fails on over-allocation.

Parameters

size	The size in bytes to allocate.

Returns: A pointer to the allocated memory or nullptr if the allocation would exceed .fail_alloc_bytes.

◆ block_malloc()

pBlock jazz_elements::Container::block_malloc ( size_t size )

inlineprotected

A spacial alloc for blocks owned by a Transaction. It clears cell_type and total_bytes assumed valid by destroy_transaction().

Parameters

size	The size in bytes to allocate.

Returns: A pointer to the allocated new Block.

◆ lock_container()

void jazz_elements::Container::lock_container ( )

inlineprotected

A private hard lock for Container-critical operations. E.g., Adding a new block to the deque.

Needless to say: Use only for a few clock-cycles over the critical part and always unlock_container() no matter what.

◆ unlock_container()

void jazz_elements::Container::unlock_container ( )

inlineprotected

Release the private hard lock for Container-critical operations.

◆ destroy_container()

StatusCode jazz_elements::Container::destroy_container ( )

protected

Destroys everything: all transactions and the buffer itself

Returns: SERVICE_NO_ERROR.

◆ from_hex()

int jazz_elements::Container::from_hex ( char c )

inlineprotected

Returns the binary value of a hex char assuming it is in range.

Parameters

c	The character which is either 0-9, a-f or A-F

Returns: The binary value of the char

◆ new_container()

StatusCode jazz_elements::Container::new_container ( )

private

Creates the buffers for new_transaction()/destroy_transaction()

Returns: SERVICE_NO_ERROR or SERVICE_ERROR_NO_MEM on RAM alloc failure.

◆ skip_space()

int jazz_elements::Container::skip_space	(	pChar &	p_in,
		int &	num_bytes
	)

inlineprivate

Skip space or tab character while parsing

Parameters

p_in	The input char stream cursor.
num_bytes	The number of bytes with data above *p_in

Returns: The number of bytes still to be read after skipping

◆ get_char()

char jazz_elements::Container::get_char	(	pChar &	p_in,
		int &	num_bytes
	)

inlineprivate

Returns the char at input cursor shifting the cursor by one or zero if there are no more characters to be read.

Parameters

p_in	The input char stream cursor.
num_bytes	The number of bytes with data above *p_in

Returns: The char read

◆ get_item_name()

bool jazz_elements::Container::get_item_name	(	pChar &	p_in,
		int &	num_bytes,
		pChar	p_out,
		bool	check_quotes = `true`,
		bool	check_colon = `true`
	)

inlineprivate

Returns the char at input cursor shifting the cursor by one or zero if there are no more characters to be read.

Parameters

p_in	The input char stream cursor.
num_bytes	The number of bytes with data above *p_in
p_out	The Name buffer that gets the answer if no error was found
check_quotes	Expects the name to be quoted (like item names) or not (like dimensions)
check_colon	Expects the name to be followed by a colon (like item names).

Returns: True on success

◆ sscanf_int32()

bool jazz_elements::Container::sscanf_int32	(	pChar &	p_in,
		int &	num_bytes,
		int &	result
	)

inlineprivate

Read an integer from the input cursor

Parameters

p_in	The input char stream cursor.
num_bytes	The number of bytes with data above *p_in
result	The result

Returns: True on success

◆ push_int_cell() [1/2]

bool jazz_elements::Container::push_int_cell	(	pChar	cell,
		pChar &	p_st,
		int *&	p_out
	)

inlineprivate

Pushes a decimal representation of an int into a tensor cell in a block.

Parameters

cell	The fixed sized buffer storing the string (actively written by p_st).
p_st	The cursor writing to cell. In case of a NA, it will be moved to &cell to clear.
p_out	A pointer to the cell in the tensor

Returns: True on success

◆ push_int_cell() [2/2]

bool jazz_elements::Container::push_int_cell	(	pChar	cell,
		pChar &	p_st,
		long long *&	p_out
	)

inlineprivate

Pushes a decimal representation of a long int into a tensor cell in a block.

Parameters

cell	The fixed sized buffer storing the string (actively written by p_st).
p_st	The cursor writing to cell. In case of a NA, it will be moved to &cell to clear.
p_out	A pointer to the cell in the tensor

Returns: True on success

◆ push_bool_cell() [1/2]

bool jazz_elements::Container::push_bool_cell	(	pChar	cell,
		pChar &	p_st,
		bool *&	p_out
	)

inlineprivate

Pushes a decimal representation of an 8 bit bool into a tensor cell in a block.

Parameters

cell	The fixed sized buffer storing the string (actively written by p_st).
p_st	The cursor writing to cell. In case of a NA, it will be moved to &cell to clear.
p_out	A pointer to the cell in the tensor

Returns: True on success

◆ push_bool_cell() [2/2]

bool jazz_elements::Container::push_bool_cell	(	pChar	cell,
		pChar &	p_st,
		uint32_t *&	p_out
	)

inlineprivate

Pushes a decimal representation of a 32 bit bool into a tensor cell in a block.

Parameters

cell	The fixed sized buffer storing the string (actively written by p_st).
p_st	The cursor writing to cell. In case of a NA, it will be moved to &cell to clear.
p_out	A pointer to the cell in the tensor

Returns: True on success

◆ push_real_cell() [1/2]

bool jazz_elements::Container::push_real_cell	(	pChar	cell,
		pChar &	p_st,
		float *&	p_out
	)

inlineprivate

Pushes a decimal representation of a 32 bit float into a tensor cell in a block.

Parameters

cell	The fixed sized buffer storing the string (actively written by p_st).
p_st	The cursor writing to cell. In case of a NA, it will be moved to &cell to clear.
p_out	A pointer to the cell in the tensor

Returns: True on success

◆ push_real_cell() [2/2]

bool jazz_elements::Container::push_real_cell	(	pChar	cell,
		pChar &	p_st,
		double *&	p_out
	)

inlineprivate

Pushes a decimal representation of a 64 bit float into a tensor cell in a block.

Parameters

cell	The fixed sized buffer storing the string (actively written by p_st).
p_st	The cursor writing to cell. In case of a NA, it will be moved to &cell to clear.
p_out	A pointer to the cell in the tensor

Returns: True on success

◆ push_time_cell()

bool jazz_elements::Container::push_time_cell	(	pChar	cell,
		pChar &	p_st,
		time_t *&	p_out,
		pChar	fmt
	)

inlineprivate

Pushes a decimal representation of a time point into a tensor cell in a block.

Parameters

cell	The fixed sized buffer storing the string (actively written by p_st).
p_st	The cursor writing to cell. In case of a NA, it will be moved to &cell to clear.
p_out	A pointer to the cell in the tensor
fmt	The address of DEF_FLOAT_TIME passed to this inline function

Returns: True on success

◆ get_type_and_shape()

bool jazz_elements::Container::get_type_and_shape	(	pChar &	p_in,
		int &	num_bytes,
		ItemHeader *	item_hea,
		MapSI &	dims
	)

private

Parse a source definition of an item in a Kind, possibly with dimensions.

Parameters

p_in	The input char stream cursor.
num_bytes	The number of bytes with data above *p_in
item_hea	The structure that receives the resulting cell_type, rank and shape.
dims	A MapSI to retrieve the dimension names.

Returns: True on success will return a valid item_hea (otherwise ite_hea is undefined).

◆ get_shape_and_size()

bool jazz_elements::Container::get_shape_and_size	(	pChar &	p_in,
		int &	num_bytes,
		int	cell_type,
		ItemHeader *	item_hea
	)

private

Parse a tensor, measure it and fail on inconsistent shape

Parameters

p_in	The input char stream cursor.
num_bytes	The number of bytes with data above *p_in
cell_type	The type of the tensor being parsed (if CELL_TYPE_UNDEFINED, it will be detected)
item_hea	The structure that receives the resulting cell_type, rank, shape and item_size.

Returns: True on success will return a valid item_hea (otherwise ite_hea is undefined).

In the case of CELL_TYPE_STRING, item_size will return the serialized total size of all the strings.

◆ fill_text_buffer()

bool jazz_elements::Container::fill_text_buffer	(	pChar &	p_in,
		int &	num_bytes,
		pChar	p_out,
		int	num_cells,
		int	is_NA[],
		int	hasLN[]
	)

private

Parse a tensor of CELL_TYPE_STRING by serializing it into a buffer compatible with a new_block(1).p_text

Parameters

p_in	The input char stream cursor.
num_bytes	The number of bytes with data above *p_in
p_out	A pointer to a buffer that has enough size for the serialized output.
num_cells	The expected number of cell for verification.
is_NA	An array to store the indices of the NA cells (to be set after the new_block() call).
hasLN	An array to store the indices of the string containing (which is serialized) and to be deserialized later.

Returns: True on success

Note**: Cells are separated by a \n character (not escaped) which is not confused with a \n inside the string which becomes escaped.

◆ fill_tensor()

bool jazz_elements::Container::fill_tensor	(	pChar &	p_in,
		int &	num_bytes,
		pBlock	p_block
	)

private

Parse a tensor of anything other than CELL_TYPE_STRING into a binary (allocated but not initialized) Block.

Parameters

p_in	The input char stream cursor.
num_bytes	The number of bytes with data above *p_in
p_block	The allocated block. Already has anything, (cell type, shape, etc.), except the data.

Returns: True on success

◆ new_text_block()

int jazz_elements::Container::new_text_block	(	pTransaction &	p_txn,
		ItemHeader &	item_hea,
		pChar &	p_in,
		int &	num_bytes,
		AttributeMap *	att = `nullptr`
	)

private

Implements the complete text block creation: fill_text_buffer()/new_block() and fixing NA and ExpandEscapeSequences()

Parameters

p_txn	Transaction for the new_block() call.
item_hea	An ItemHeader computed by a previous call to get_type_and_shape()
p_in	The input char stream cursor.
num_bytes	The number of bytes with data above *p_in
att	An AttributeMap for the new_block() call.

Returns: StatusCode like a new_block() call

◆ tensor_int_as_text()

int jazz_elements::Container::tensor_int_as_text	(	pBlock	p_block,
		pChar	p_dest,
		pChar	p_fmt
	)

private

Serializes a Tensor of CELL_TYPE_BYTE, CELL_TYPE_INTEGER, CELL_TYPE_FACTOR, CELL_TYPE_GRADE or CELL_TYPE_LONG_INTEGER as a string.

Parameters

p_block	The raw block to be serialized as text (must have one of the types above).
p_dest	Optionally, a pointer with the address to which the output is serialized. (If nullptr, only size counting is done)
p_fmt	Optionally, format specifier that is understood by sprintf (default is i)

Returns: The length in bytes required to store the output if p_dest == nullptr

The serialization includes NA identification, commas spaces an square brackets to define the shape.

◆ tensor_bool_as_text()

int jazz_elements::Container::tensor_bool_as_text	(	pBlock	p_block,
		pChar	p_dest
	)

private

Serializes a Tensor of CELL_TYPE_BYTE_BOOLEAN or CELL_TYPE_BOOLEAN as a string.

Parameters

p_block	The raw block to be serialized as text (must have one of the types above).
p_dest	Optionally, a pointer with the address to which the output is serialized. (If nullptr, only size counting is done)

Returns: The length in bytes required to store the output if p_dest == nullptr

The serialization includes NA identification, commas spaces an square brackets to define the shape.

◆ tensor_float_as_text()

int jazz_elements::Container::tensor_float_as_text	(	pBlock	p_block,
		pChar	p_dest,
		pChar	p_fmt
	)

private

Serializes a Tensor of CELL_TYPE_SINGLE or CELL_TYPE_DOUBLE as a string.

Parameters

p_block	The raw block to be serialized as text (must have one of the types above).
p_dest	Optionally, a pointer with the address to which the output is serialized. (If nullptr, only size counting is done)
p_fmt	Optionally, format specifier that is understood by sprintf (default is f)

Returns: The length in bytes required to store the output if p_dest == nullptr

The serialization includes NA identification, commas spaces an square brackets to define the shape.

◆ tensor_string_as_text()

int jazz_elements::Container::tensor_string_as_text	(	pBlock	p_block,
		pChar	p_dest
	)

private

Serializes a Tensor of CELL_TYPE_STRING as a string.

Parameters

p_block	The raw block to be serialized as text (must have one of the types above).
p_dest	Optionally, a pointer with the address to which the output is serialized. (If nullptr, only size counting is done)

Returns: The length in bytes required to store the output if p_dest == nullptr

The serialization includes NA identification, double quotes, commas spaces an square brackets to define the shape.

NOTE** that this escapes all non-vanilla ASCI characters, non printable (below 32), the blackslash and the double quote.

How UTF-8 works

The RFC http://www.ietf.org/rfc/rfc3629.txt says:

Char. number range  | UTF-8 octet sequence
(hexadecimal)       | (binary)
--------------------+---------------------------------------------
0000 0000-0000 007F | 0xxxxxxx
0000 0080-0000 07FF | 110xxxxx 10xxxxxx
0000 0800-0000 FFFF | 1110xxxx 10xxxxxx 10xxxxxx
0001 0000-0010 FFFF | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

◆ tensor_time_as_text()

int jazz_elements::Container::tensor_time_as_text	(	pBlock	p_block,
		pChar	p_dest,
		pChar	p_fmt
	)

private

Serializes a Tensor of CELL_TYPE_TIME as a string.

Parameters

p_block	The raw block to be serialized as text (must have one of the types above).
p_dest	Optionally, a pointer with the address to which the output is serialized. (If nullptr, only size counting is done)
p_fmt	Optionally, format specifier that is understood by sprintf (default is Y-m-d H:M:S)

Returns: The length in bytes required to store the output if p_dest == nullptr

The serialization includes NA identification, commas spaces an square brackets to define the shape.

◆ tensor_tuple_as_text()

int jazz_elements::Container::tensor_tuple_as_text	(	pTuple	p_tuple,
		pChar	p_dest,
		pChar	p_fmt,
		int	item_len[]
	)

private

Serializes a Tuple as a string.

Parameters

p_tuple	The raw Tuple to be serialized as text.
p_dest	Optionally, a pointer with the address to which the output is serialized. (If nullptr, only size counting is done)
p_fmt	Optionally, format specifier that will be applied to all items. (default is each type uses its default)
item_len	A buffer storing the length of each item: computed by tensor_tuple_as_text(p_dest == nullptr), used by tensor_tuple_as_text(p_dest != nullptr).

Returns: The length in bytes required to store the output if p_dest == nullptr

The serialization includes item names and the content of each tensor as written by the tensor methods.

◆ tensor_kind_as_text()

int jazz_elements::Container::tensor_kind_as_text	(	pKind	p_kind,
		pChar	p_dest
	)

private

Serializes a Kind as a string.

Parameters

p_kind	The raw Kind to be serialized as text.
p_dest	Optionally, a pointer with the address to which the output is serialized. (If nullptr, only size counting is done)

Returns: The length in bytes required to store the output if p_dest == nullptr

The serialization includes item names, types and shapes.

◆ opening_brackets()

void jazz_elements::Container::opening_brackets	(	int	rank,
		pChar &	p_ret
	)

inlineprivate

Writes opening brackets for a tensor

Parameters

rank	The tensor rank
p_ret	The cursor to the output buffer

◆ as_shape()

pChar jazz_elements::Container::as_shape	(	int	rank,
		int	dim[],
		pChar	p_ret,
		pKind	p_kind
	)

inlineprivate

Writes the shape of a Tensor in a Kind

Parameters

rank	The tensor rank
p_ret	The cursor to the output buffer
dim	The shape
p_kind	The kind from which dimension names should be read

Returns: The cursor to the output buffer updated by the text written

◆ as_hex()

void jazz_elements::Container::as_hex	(	pChar &	p_dest,
		uint8_t	bl
	)

inlineprivate

Writes a char as 0xFF

Parameters

p_dest	The cursor to the output buffer
bl	The character

◆ separator()

void jazz_elements::Container::separator	(	int	rank_1,
		int	dim[],
		int	idx[],
		pChar &	p_ret
	)

inlineprivate

Writes the separator between two cells in a tensor (counting brackets, comma, ..)

Parameters

rank_1	The tensor rank - 1
dim	The shape
idx	The current index expressed inside the shape
p_ret	The cursor to the output buffer

◆ separator_len()

int jazz_elements::Container::separator_len	(	int	rank_1,
		int	dim[],
		int	idx[]
	)

inlineprivate

Computes the length of the separator between two cells in a tensor (counting brackets, comma, ..)

Parameters

rank_1	The tensor rank - 1
dim	The shape
idx	The current index expressed inside the shape

Returns: The length taken by the separator

The documentation for this class was generated from the following files:

container.h
container.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

One-shot Block allocation

Instances and inheritance

Container descendants

Scope of jazz_elements

Code execution

new_block()

Constructor & Destructor Documentation

◆ Container()

Member Function Documentation

◆ start()

◆ shut_down()

◆ enter_read()

◆ enter_write()

◆ leave_read()

◆ leave_write()

◆ new_block() [1/8]

◆ new_block() [2/8]

◆ new_block() [3/8]

◆ new_block() [4/8]

◆ new_block() [5/8]

◆ new_block() [6/8]

◆ new_block() [7/8]

◆ new_block() [8/8]

◆ new_transaction()

◆ destroy_transaction()

◆ get() [1/6]

◆ get() [2/6]

◆ get() [3/6]

◆ locate() [1/2]

◆ header() [1/4]

◆ header() [2/4]

◆ put() [1/2]

◆ new_entity() [1/2]

◆ remove() [1/2]

◆ copy() [1/2]

◆ exec()

◆ modify()

◆ as_locator()

◆ get() [4/6]

◆ get() [5/6]

◆ get() [6/6]

◆ locate() [2/2]

◆ header() [3/4]

◆ header() [4/4]

◆ put() [2/2]

◆ new_entity() [2/2]

◆ remove() [2/2]

◆ copy() [2/2]

◆ unwrap_received() [1/2]

◆ unwrap_received() [2/2]

◆ base_names()

◆ malloc()

◆ block_malloc()

◆ lock_container()

◆ unlock_container()

◆ destroy_container()

◆ from_hex()

◆ new_container()

◆ skip_space()

◆ get_char()

◆ get_item_name()

◆ sscanf_int32()

◆ push_int_cell() [1/2]

◆ push_int_cell() [2/2]

◆ push_bool_cell() [1/2]

◆ push_bool_cell() [2/2]

◆ push_real_cell() [1/2]

◆ push_real_cell() [2/2]

◆ push_time_cell()

◆ get_type_and_shape()

◆ get_shape_and_size()

◆ fill_text_buffer()

◆ fill_tensor()