Tuple: A Jazz Block with multiple Tensors. More...

#include <tuple.h>

Inheritance diagram for jazz_elements::Tuple:

Public Member Functions
StatusCode	new_tuple (int num_items, pBlock blocks[], Name p_names[], int num_bytes, AttributeMap *att=nullptr)

char *	item_name (int idx)

int	index (pChar name)

pBlock	get_block (int idx)

bool	is_a (pKind kind)

int	audit ()

Public Member Functions inherited from jazz_elements::Block
void	set_dimensions (int *p_dim)

void	get_dimensions (int *p_dim)

bool	validate_index (int *p_idx)

int	validate_offset (int offset)

int	get_offset (int *p_idx)

void	get_index (int offset, int *p_idx)

char *	get_string (int *p_idx)

char *	get_string (int offset)

void	set_string (int p_idx, const char p_str)

void	set_string (int offset, const char *p_str)

char *	get_attribute (int attribute_id)

void	set_attributes (AttributeMap *all_att)

void	get_attributes (AttributeMap *all_att)

void	init_string_buffer ()

bool	find_NAs_in_tensor ()

int *	align64bit (uintptr_t ipt)
	Align a pointer (as uintptr_t) to the next 8 byte boundary assuming the block is aligned.

int *	p_attribute_keys ()

pStringBuffer	p_string_buffer ()

int	get_string_offset (pStringBuffer psb, const char *p_str)

bool	is_a_filter ()
	Check (in depth) the validity of a filter.

bool	can_filter (pBlock p_block)

void	close_block (int set_has_NA=SET_HAS_NA_FALSE, bool set_hash=true, bool set_time=true)

bool	check_hash ()

Additional Inherited Members
Data Fields inherited from jazz_elements::StaticBlockHeader
int	cell_type
	The type for the cells in the tensor. See CELL_TYPE_*.

int	size
	The total number of cells in the tensor.

TimePoint	created
	Timestamp when the block was created.

int	rank
	The number of dimensions.

TensorDim	range
	The dimensions of the tensor in terms of ranges (Max. size is 2 Gb.)

int	num_attributes
	Number of elements in the JazzAttributesMap.

int	total_bytes
	Total size of the block everything included.

bool	has_NA
	If true, at least one value is a NA and block requires NA-aware arithmetic.

uint64_t	hash64
	Hash of everything but the header.

Tensor	tensor
	A tensor for type cell_type and dimensions set by Block.set_dimensions()

Detailed Description

Tuple: A Jazz Block with multiple Tensors.

Can be simplified as "An instance of a **Kind**" although that is not exactly what it is. It is an array of Tensors and it can match one or more Kinds if its .is_a(<kind>) method returns true.

Physically, like a Kind, it is a single block with some differences:

It holds data and metadata.
It has constant values for the dimensions.
It has a one step creation process: new_tuple().
It also stores all the Blocks "as is" in the same space (after its header, vector of CELL_TYPE_KIND_ITEM, attribute keys and StringBuffer)
The data stored &tensor is the metadata (like in a Kind) and the method .block(item) returns a pointer to each Block.
A Tuple is a Block of type CELL_TYPE_TUPLE_ITEM (instead of CELL_TYPE_KIND_ITEM).
The StringBuffer contains the item names and Tuple attributes. Blocks may have their own StringBuffers

Also, Tuples should define, if the Container sets them as expected, the attribute:

BLOCK_ATTRIB_BLOCKTYPE as the const "Tuple"

Creating Tuples

More advanced Tuple functionalities (including other ways of creating tuples) can be done by Containers. This class, has a minimum functionality to build Tuples: new_tuple() to do the basic building. It does not includes creating Tuples from other Tuples by appending the names.

Using Tuples

Like any Block, it is a moveable structure that can be edited by this class. Channel-wise, Volatile, Persistence or via the http API, it is just a Block. Note:

It has a new method, .block(item), that returns the address of an item.
It has an is_a() method that verifies if it satisfies a Kind.
It has an audit() method to check validity.
Besides that, it is just a "big Block" whose header has a total_bytes that includes all the metadata and data.

Member Function Documentation

◆ new_tuple()

StatusCode jazz_elements::Tuple::new_tuple	(	int	num_items,
		pBlock	blocks[],
		Name	p_names[],
		int	num_bytes,
		AttributeMap *	att = `nullptr`
	)

inline

Initializes a Tuple object (step 1): Initializes the space.

Parameters

num_items	The number of items the Tuple will have == size of the p_blocks-> and p_names->
blocks	An array of pointers to the blocks to be included in the Tuple.
p_names	An array of Name by which the items will go.
num_bytes	The size in bytes allocated. Should be enough for all names, data, ItemHeaders and attributes.
att	The attributes for the Tuple. Set "as is", without adding BLOCK_ATTRIB_BLOCKTYPE or anything.

Returns: 0, SERVICE_ERROR_NO_MEM, SERVICE_ERROR_WRONG_TYPE, SERVICE_ERROR_WRONG_NAME, SERVICE_ERROR_WRONG_ARGUMENTS

◆ item_name()

char * jazz_elements::Tuple::item_name ( int idx )

inline

Get the name for an item of a Tuple by index without checking index range.

Parameters

idx	The index of the item.

Returns: A pointer to where the (zero ended) string is stored in the Block or nullptr for an invalid index.

NOTE: Use the pointer as read-only (more than one cell may point to the same value) and never try to free it.

◆ index()

int jazz_elements::Tuple::index ( pChar name )

inline

Get the index for an item of a Tuple by name.

Parameters

name	The name of the item.

Returns: A invalid index or -1 for "not found".

◆ get_block()

pBlock jazz_elements::Tuple::get_block ( int idx )

inline

Get a Block from a Tuple by item index.

Parameters

idx	The index of the item.

Returns: The block stored in the tuple or nullptr for an invalid index.

NOTE: Use the pointer as read-only (more than one cell may point to the same value) and never try to free it.

◆ is_a()

bool jazz_elements::Tuple::is_a ( pKind kind )

inline

Verifies if a Tuple is of a Kind.

Parameters

kind	The possibly matching Kind.

Returns: True if the Tuple can be linked to a Kind (regardless of BLOCK_ATTRIB_KIND)

◆ audit()

int jazz_elements::Tuple::audit ( )

Check the internal validity of a Tuple (item structure, dimensions, etc.)

Returns: MIXED_TYPE_INVALID on error or MIXED_TYPE_TUPLE if every check passes ok.

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

tuple.h
tuple.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Creating Tuples

Using Tuples

Member Function Documentation

◆ new_tuple()

◆ item_name()

◆ index()

◆ get_block()

◆ is_a()

◆ audit()