Persisted: A Service to manage data objects in LMDB. More...

#include <persisted.h>

Inheritance diagram for jazz_elements::Persisted:

Public Member Functions
	Persisted (pLogger a_logger, pConfigFile a_config)

virtual pChar const	id ()

StatusCode	start ()
	Starts the service, checking the environment and building the databases.

StatusCode	shut_down ()
	Shuts down the Persisted Service.

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	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_FULL_BLOCK)

virtual StatusCode	new_entity (Locator &where)

virtual StatusCode	remove (Locator &where)

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

void	base_names (BaseNames &base_names)

bool	dbi_exists (Name dbi_name)
	Check the internal std::map to see if a (dbi) database name exists.

bool	is_running ()
	Check if the service is running.

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	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	header (StaticBlockHeader &hea, pChar p_what)

virtual StatusCode	header (pTransaction &p_txn, pChar p_what)

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

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

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

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

virtual StatusCode	new_entity (pChar p_where)

virtual StatusCode	new_entity (Locator &where)

virtual StatusCode	remove (pChar p_where)

virtual StatusCode	remove (Locator &where)

virtual StatusCode	copy (pChar p_where, pChar p_what)

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

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

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	locate (Locator &location, 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	locate (Locator &location, 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)

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)

Private Member Functions
pBlock	lock_pointer_to_block (Locator &what, pMDB_txn &p_txn)
	Locates a block doing an mdb_get() leaving the transaction open.

void	done_pointer_to_block (pMDB_txn &p_txn)
	Completes the transaction started by lock_pointer_to_block() doing a mdb_txn_commit() which invalidates the pointer.

bool	open_all_databases ()

void	close_all_databases ()

StatusCode	new_database (pChar name)

StatusCode	remove_database (pChar name)

void	log_lmdb_err (int loglevel, int lmdb_err, const char *msg)
	A nicer presentation for LMDB error messages.

Private Attributes
DBImap	source_dbi = {}
	The lmdb MDB_dbi handles for each source.

JazzLmdbOptions	lmdb_opt
	The LMDB options.

MDB_env *	lmdb_env = nullptr
	The LMDB environment.

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

pConfigFile	p_conf
	The configuration file.

Protected Member Functions inherited from jazz_elements::Container
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 inherited from jazz_elements::Container
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.

Detailed Description

Persisted: A Service to manage data objects in LMDB.

This Container implements the full crud (.get(), .header(), .put(), .new_entity(), .remove(), .copy()) interface storing blocks in LMDB tables.

For reference:

See Container and each of the crud methods in this class.
Each entity (whose name is parsed by Container.as_locator()) is a named LMDB (dbi) database.
Outside Jazz, the database files can be managed (even while running) with LMDB utils: mdb_copy, mdb_drop, mdb_dump, mdb_load & mdb_stat
For how LMDB is used, see http://www.lmdb.tech/doc/ for coding reference.
For specific details, that may be experimented with, see the config file: server/config/jazz_config.ini

Constructor & Destructor Documentation

◆ Persisted()

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

Initialize the Persisted Container without starting it.

Parameters

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

Member Function Documentation

◆ id()

pChar const jazz_elements::Persisted::id ( )

virtual

Return object ID.

Returns: A string identifying the object that is especially useful to track uplifts and versions.

Reimplemented from jazz_elements::Service.

◆ start()

StatusCode jazz_elements::Persisted::start ( )

virtual

Starts the service, checking the environment and building the databases.

Returns: SERVICE_NO_ERROR if successful, some error and log(LOG_MISS, "further details") if not.

This service initialization checks configuration values related with persistence and starts LMDB with configured values.

Reimplemented from jazz_elements::Container.

◆ shut_down()

StatusCode jazz_elements::Persisted::shut_down ( )

virtual

Shuts down the Persisted Service.

Returns: SERVICE_NO_ERROR if successful, some error and log(LOG_MISS, "further details") if not.

Reimplemented from jazz_elements::Container.

◆ get() [1/9]

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

virtual

Native (Persistence) interface complete Block retrieval.

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. E.g. //lmdb/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 from jazz_elements::Container.

◆ get() [2/9]

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

virtual

Native (Persistence) interface selection of rows in a Block retrieval.

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. E.g. //lmdb/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 from jazz_elements::Container.

◆ get() [3/9]

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

virtual

Native (Persistence) interface selection of a tensor in a Tuple retrieval.

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. E.g. //lmdb/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 from jazz_elements::Container.

◆ header() [1/6]

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

virtual

Native (Persistence) interface metadata of a Block retrieval.

Parameters

hea	A StaticBlockHeader structure that will receive the metadata.
what	Some Locator to the block. E.g. //lmdb/entity/key

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), 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 from jazz_elements::Container.

◆ header() [2/6]

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

virtual

Native (Persistence) interface metadata of a Block retrieval.

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. E.g. //lmdb/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 from jazz_elements::Container.

◆ put() [1/3]

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

virtual

Native (Persistence) interface for Block storing

Parameters

where	Some destination parsed by as_locator()
p_block	The Block to be stored in Persistence. 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_NO_ERROR on success or some negative value (error).

NOTE**: This updates the calling block's creation time and hash64.

Reimplemented from jazz_elements::Container.

◆ new_entity() [1/3]

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

virtual

Native (Persistence) interface for creating databases

Parameters

where The name of the LMDB database to be created. E.g. //lmdb/entity compiled.

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

Reimplemented from jazz_elements::Container.

◆ remove() [1/3]

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

virtual

Native (Persistence) interface for deleting databases and blocks:

Parameters

where Some Locator to the block or database to be removed. E.g. //lmdb/entity/key or //lmdb/entity compiled.

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

Reimplemented from jazz_elements::Container.

◆ copy() [1/3]

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

virtual

Native (Persistence) interface for Block copying (inside the Persistence).

Parameters

where	Some destination parsed by as_locator()
what	Some Locator to the block. E.g. //lmdb/entity/key

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

Reimplemented from jazz_elements::Container.

◆ base_names()

void jazz_elements::Persisted::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 Persisted object has used-defined databases containing anything, these databases can have any names as long as they do not interfere with existing base names. The API object will forward names that do not match any base names to Persisted in case they are the name of a database (and will fail otherwise).

Besides these user-defined names, there is a number of reserved databases that keep track of things and are found in the configuration.

"static" is a database of objects with attributes BLOCK_ATTRIB_URL and BLOCK_ATTRIB_MIMETYPE exposed via the / API.

◆ dbi_exists()

bool jazz_elements::Persisted::dbi_exists ( Name dbi_name )

Check the internal std::map to see if a (dbi) database name exists.

Parameters

dbi_name The location of a Block inside LMDB.

Returns: True if exists.

◆ is_running()

bool jazz_elements::Persisted::is_running ( )

inline

Check if the service is running.

Returns: True if the service is running.

◆ lock_pointer_to_block()

pBlock jazz_elements::Persisted::lock_pointer_to_block	(	Locator &	what,
		pMDB_txn &	lm_tx
	)

private

Locates a block doing an mdb_get() leaving the transaction open.

Parameters

what	The location of a Block inside LMDB.
lm_tx	the transcation created by a lock_pointer_to_block() call.

Returns: The pointer to the block (can only be read and requires a done_pointer_to_block() to close the transaction) or nullptr (+ log INFO) on error.

NOTE: This requires a subsequent done_pointer_to_block() call.

◆ done_pointer_to_block()

void jazz_elements::Persisted::done_pointer_to_block ( pMDB_txn & lm_tx )

private

Completes the transaction started by lock_pointer_to_block() doing a mdb_txn_commit() which invalidates the pointer.

Parameters

lm_tx the transcation created by a lock_pointer_to_block() call.

◆ open_all_databases()

bool jazz_elements::Persisted::open_all_databases ( )

private

Locate all the named databases in the current LMDB environment, add them to the source[] vector and open them all for reading.

Returns: true if successful, false and log(LOG_MISS, "further details") if not.

◆ close_all_databases()

void jazz_elements::Persisted::close_all_databases ( )

private

Close all named databases on LMDB leaving them ready for a subsequent opening.

This closes used LMDB handles one by one via mdb_dbi_close().

◆ new_database()

StatusCode jazz_elements::Persisted::new_database ( pChar name )

private

Create a new LMDB named database and add it as a new source to the source_dbi[] map.

Parameters

name	The name of the source to be added.

Returns: SERVICE_NO_ERROR on success or some negative value and log(LOG_MISS, "further details") on failure.

◆ remove_database()

StatusCode jazz_elements::Persisted::remove_database ( pChar name )

private

Kill a source, both from the LMDB persistence and from the source[] vector.

Parameters

name	The name of the source to be killed.

Returns: SERVICE_NO_ERROR on success or some negative value and log(LOG_MISS, "further details") on failure.

NOTE: kill_source() is EXTREMELY not thread safe! Indices to ALL sources may change.

◆ log_lmdb_err()

void jazz_elements::Persisted::log_lmdb_err	(	int	loglevel,
		int	lmdb_err,
		const char *	msg
	)

private

A nicer presentation for LMDB error messages.

Parameters

loglevel	The log level with which the messages have to be delivered.
lmdb_err	The error code returned by lmdb.
msg	An additional explanatory message about the circumstances how it happened.

NOTE: One call to this produces two log lines: one with the translation of the lmdb code the second one with msg.

◆ get() [4/9]

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 from jazz_elements::Container.

◆ get() [5/9]

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 from jazz_elements::Container.

◆ get() [6/9]

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 from jazz_elements::Container.

◆ get() [7/9]

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 from jazz_elements::Container.

◆ get() [8/9]

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 from jazz_elements::Container.

◆ get() [9/9]

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 from jazz_elements::Container.

◆ header() [3/6]

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 from jazz_elements::Container.

◆ header() [4/6]

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 from jazz_elements::Container.

◆ header() [5/6]

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 from jazz_elements::Container.

◆ header() [6/6]

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 from jazz_elements::Container.

◆ put() [2/3]

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 from jazz_elements::Container.

◆ put() [3/3]

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 from jazz_elements::Container.

◆ new_entity() [2/3]

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 from jazz_elements::Container.

◆ new_entity() [3/3]

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 from jazz_elements::Container.

◆ remove() [2/3]

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 from jazz_elements::Container.

◆ remove() [3/3]

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 from jazz_elements::Container.

◆ copy() [2/3]

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 from jazz_elements::Container.

◆ copy() [3/3]

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 from jazz_elements::Container.

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

persisted.h
persisted.cpp

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

For reference:

Constructor & Destructor Documentation

◆ Persisted()

Member Function Documentation

◆ id()

◆ start()

◆ shut_down()

◆ get() [1/9]

◆ get() [2/9]

◆ get() [3/9]

◆ header() [1/6]

◆ header() [2/6]

◆ put() [1/3]

◆ new_entity() [1/3]

◆ remove() [1/3]

◆ copy() [1/3]

◆ base_names()

◆ dbi_exists()

◆ is_running()

◆ lock_pointer_to_block()

◆ done_pointer_to_block()

◆ open_all_databases()

◆ close_all_databases()

◆ new_database()

◆ remove_database()

◆ log_lmdb_err()

◆ get() [4/9]

◆ get() [5/9]

◆ get() [6/9]

◆ get() [7/9]

◆ get() [8/9]

◆ get() [9/9]

◆ header() [3/6]

◆ header() [4/6]

◆ header() [5/6]

◆ header() [6/6]

◆ put() [2/3]

◆ put() [3/3]

◆ new_entity() [2/3]

◆ new_entity() [3/3]

◆ remove() [2/3]

◆ remove() [3/3]

◆ copy() [2/3]

◆ copy() [3/3]