Public Types
enum	access_mode { read_only, writable, writeable_no_create }

Public Member Functions
	database (std::string const &path, access_mode am, bool access_tick_enabled=true)
	Creates a database instance give the path of the file to use. More...

template<typename File >
	database (std::shared_ptr< File > file, std::unique_ptr< system_page_size_interface > &&page_size, std::unique_ptr< region::factory > &&region_factory, bool access_tick_enabled=true)
	Create a database from a pre-opened file. More...

template<typename File >
	database (std::shared_ptr< File > file, bool access_tick_enabled=true)

	database (database &&)=delete

	database (database const &)=delete

database &	operator= (database &&)=delete

database &	operator= (database const &)=delete

std::uint64_t	size () const noexcept
	Returns the logical size of the data store. More...

std::string	path () const
	Returns the path of the file in which this database is contained.

void	sync (unsigned revision=head_revision)
	Update to a specified revision of the data.

typed_address< trailer >	older_revision_footer_pos (unsigned revision) const
	Returns the address of the footer of a specified revision. More...

std::unique_lock< file::range_lock > *	upgrade_to_write_lock ()

std::time_t	latest_time () const

bool	is_writable () const noexcept

virtual auto	get (address addr, std::size_t size, bool initialized, bool writable) const -> std::shared_ptr< void const >

class storage const &	storage () const noexcept
	For unit testing.

void	close ()

header const &	get_header () const noexcept

typed_address< trailer >	footer_pos () const noexcept

unsigned	get_current_revision () const
	Returns the generation number to which the database is synced. More...

std::string	get_sync_name () const
	Returns the name of the store's synchronisation object. More...

std::string	shared_memory_name () const

virtual address	allocate (std::uint64_t bytes, unsigned align)
	Appends an amount of storage to the database. More...

virtual void	truncate (std::uint64_t size)

void	set_new_footer (typed_address< trailer > new_footer_pos)
	Call as part of completing a transaction. More...

void	protect (address const first, address const last)

void	set_id (uuid const &id) noexcept

shared const *	get_shared () const

shared *	get_shared ()

std::shared_ptr< index::index_base > &	get_mutable_index (enum pstore::trailer::indices const which) const
	Returns a pointer to an index base. More...

std::shared_ptr< trailer const >	get_footer () const

template<typename File >
auto	get_footer_pos (File &file) -> typed_address< trailer >


file::file_base const *	file () const
	Returns the file in which this database is contained.

file::file_base *	file ()


std::shared_ptr< void const >	getro (address const addr, std::size_t const size) const

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
std::shared_ptr< T const >	getro (extent< T > const &ex) const
	Load a block of data starting at the address and size specified by `ex`. More...

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
std::shared_ptr< T const >	getro (typed_address< T > const addr) const
	Returns a pointer to a immutable instance of type T. More...

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
std::shared_ptr< T const >	getro (typed_address< T > const addr, std::size_t const elements) const
	Returns a pointer to a read-only array of instances of type T. More...


std::shared_ptr< void >	getrw (address const addr, std::size_t const size)
	Load a block of data starting at address `addr` and of `size` bytes. More...

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
std::shared_ptr< T >	getrw (extent< T > const &ex)
	Loads a block of storage at the address and size given by `ex`. More...

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
std::shared_ptr< T >	getrw (typed_address< T > addr)
	Returns a pointer to a mutable instance of type T. More...

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
std::shared_ptr< T >	getrw (typed_address< T > const addr, std::size_t const elements)
	Returns a pointer to a mutable array of instances of type T. More...

Static Public Member Functions
static void	build_new_store (file::file_base &file)
	Constructs the basic data store structures in an empty file. More...

static constexpr bool	small_files_enabled () noexcept

static bool	crc_checks_enabled ()
	Returns true if CRC checks are enabled. More...

enum	vacuum_mode { disabled, immediate, background }

void	set_vacuum_mode (vacuum_mode const mode) noexcept

vacuum_mode	get_vacuum_mode () const noexcept

Constructor & Destructor Documentation

◆ database() [1/2]

pstore::database::database	(	std::string const &	path,
		access_mode	am,
		bool	access_tick_enabled = `true`
	)

explicit

Creates a database instance give the path of the file to use.

Parameters

path	The path of the file containing the database.
am	The requested access mode. If the file does not exist and writable access is requested, a new empty database is created. If read-only access is requested and the file does not exist, an error is raised.

◆ database() [2/2]

template<typename File >

pstore::database::database	(	std::shared_ptr< File >	file,
		std::unique_ptr< system_page_size_interface > &&	page_size,
		std::unique_ptr< region::factory > &&	region_factory,
		bool	access_tick_enabled = `true`
	)

explicit

Create a database from a pre-opened file.

This interface is intended to enable the database class to be unit tested.

Member Function Documentation

◆ allocate()

pstore::address pstore::database::allocate	(	std::uint64_t	bytes,
		unsigned	align
	)

virtual

Appends an amount of storage to the database.

As an append-only system, this function provides the means by which data is recorded in the underlying storage; it is responsible for increasing the amount of available storage when necessary.

Note: Before calling this function it is important that the global write-lock is held (usually through use of transaction<>). Failure to do so will cause race conditions between processes accessing the store.

Parameters

bytes	The number of bytes to be allocated.
align	The alignment of the allocated storage. Must be a power of 2.

Returns: The address of the newly allocated storage.

OCLINT(PH - don't warn that this is a constant)

◆ build_new_store()

void pstore::database::build_new_store ( file::file_base & file )

static

Constructs the basic data store structures in an empty file.

On return, the file will contain the correct header and a single, empty, transaction.

◆ crc_checks_enabled()

bool pstore::database::crc_checks_enabled ( )

static

Returns true if CRC checks are enabled.

The library uses simple CRC checks to ensure the validity of its internal data structures. When fuzz testing, these can be disabled to increase the probability of the fuzzer uncovering a real bug. Always enabled otherwise.

◆ get_current_revision()

unsigned pstore::database::get_current_revision ( ) const

inline

Returns the generation number to which the database is synced.

Note: This generation number doesn't count an open transaction.

◆ get_mutable_index()

std::shared_ptr<index::index_base>& pstore::database::get_mutable_index ( enum pstore::trailer::indices const which ) const

inline

Returns a pointer to an index base.

Parameters

which An index type from which the index will be read.

◆ get_sync_name()

std::string pstore::database::get_sync_name ( ) const

inline

Returns the name of the store's synchronisation object.

This is set of 20 letters (sync_name_length) from a 32 character alphabet whose value is derived from the store's ID. Assuming a truly uniform distribution, we have a collision probability of 1/32^20 which should be more than small enough for our purposes.

◆ getro() [1/4]

std::shared_ptr<void const> pstore::database::getro	(	address const	addr,
		std::size_t const	size
	)		const

inline

Load a block of data starting at address addr and of size bytes.

Parameters

addr	The starting address of the data block to be loaded.
size	The size of the data block to be loaded.

Returns: A read-only pointer to the loaded data.

◆ getro() [2/4]

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>

std::shared_ptr<T const> pstore::database::getro ( extent< T > const & ex ) const

inline

Load a block of data starting at the address and size specified by ex.

Parameters

ex	The extent of of the data to be loaded.

Returns: A read-only pointer to the loaded data.

◆ getro() [3/4]

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>

std::shared_ptr<T const> pstore::database::getro ( typed_address< T > const addr ) const

inline

Returns a pointer to a immutable instance of type T.

Template Parameters

T	The type to be loaded. Must be standard-layout.

Parameters

addr	The address at which the data begins.

Returns: A read-only pointer to the loaded data.

◆ getro() [4/4]

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>

std::shared_ptr<T const> pstore::database::getro	(	typed_address< T > const	addr,
		std::size_t const	elements
	)		const

inline

Returns a pointer to a read-only array of instances of type T.

Template Parameters

T	The type to be loaded. Must be standard-layout.

Parameters

addr	The address at which the data begins.
elements	The number of elements in the T[] array.

Returns: A read-only pointer to the loaded data.

◆ getrw() [1/4]

std::shared_ptr<void> pstore::database::getrw	(	address const	addr,
		std::size_t const	size
	)

inline

Load a block of data starting at address addr and of size bytes.

A collection of functions which obtain a non-const pointer to database storage. These functions should only be called by the transaction code. Data outside of an open transaction is always read-only and the underlying memory is marked read-only. Writing through the pointer returned by these functions may cause client code to crash if the address lies outside the range of the expected range.

Parameters

addr	The starting address of the data block to be loaded.
size	The size of the data block to be loaded.

Returns: A mutable pointer to the loaded data.

◆ getrw() [2/4]

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>

std::shared_ptr<T> pstore::database::getrw ( extent< T > const & ex )

inline

Loads a block of storage at the address and size given by ex.

Parameters

ex	The extent of the data.

Returns: A mutable pointer to the loaded data.

◆ getrw() [3/4]

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>

std::shared_ptr<T> pstore::database::getrw ( typed_address< T > addr )

inline

Returns a pointer to a mutable instance of type T.

Parameters

addr	The address at which the data begins.

Returns: A mutable pointer to the loaded data.

◆ getrw() [4/4]

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>

std::shared_ptr<T> pstore::database::getrw	(	typed_address< T > const	addr,
		std::size_t const	elements
	)

inline

Returns a pointer to a mutable array of instances of type T.

Parameters

addr	The address at which the data begins.
elements	The number of elements in the T[] array.

Returns: A mutable pointer to the loaded data.

◆ older_revision_footer_pos()

typed_address< trailer > pstore::database::older_revision_footer_pos ( unsigned revision ) const

Returns the address of the footer of a specified revision.

Parameters

revision The revision number. Should not be pstore::head_revision and should be less than or equal to the current revision number (as returned by database::get_current_revision(). In this event, an unknown_revision error is raised.

Note: This is a const member function and therefore cannot "see" revisions later than the old currently synced because to do so may require additional space to be mapped.

◆ set_new_footer()

void pstore::database::set_new_footer ( typed_address< trailer > new_footer_pos )

Call as part of completing a transaction.

We update the database records to that the new footer is recorded.

◆ size()

std::uint64_t pstore::database::size ( ) const

inlinenoexcept

Returns the logical size of the data store.

The local size of the data store is the number of bytes used, including both the data and meta-data. This may be less than the size of the physical disk file.

◆ truncate()

void pstore::database::truncate ( std::uint64_t size )

virtual

OCLINT(PH - don't warn that this is a constant)

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

include/pstore/core/database.hpp
lib/core/database.cpp

Public Types

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

◆ database() [1/2]

◆ database() [2/2]

Member Function Documentation

◆ allocate()

◆ build_new_store()

◆ crc_checks_enabled()

◆ get_current_revision()

◆ get_mutable_index()

◆ get_sync_name()

◆ getro() [1/4]

◆ getro() [2/4]

◆ getro() [3/4]

◆ getro() [4/4]

◆ getrw() [1/4]

◆ getrw() [2/4]

◆ getrw() [3/4]

◆ getrw() [4/4]

◆ older_revision_footer_pos()

◆ set_new_footer()

◆ size()

◆ truncate()