Implementation of a Copy-On-Write (CoW) using jau::darray as the underlying storage, exposing lock-free read operations using SC-DRF atomic synchronization. More...

#include <cow_darray.hpp>

Inheritance diagram for jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >:

Collaboration diagram for jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >:

Public Types
typedef Value_type	value_type

typedef value_type *	pointer

typedef const value_type *	const_pointer

typedef value_type &	reference

typedef const value_type &	const_reference

typedef Size_type	size_type

typedef std::make_signed< size_type >::type	difference_type

typedef Alloc_type	allocator_type

typedef darray< value_type, allocator_type, size_type, use_memmove, use_realloc, sec_mem >	storage_t

typedef std::shared_ptr< storage_t >	storage_ref_t

typedef bool	darray_tag
	Used to determine whether this type is a darray or has a darray, see ::is_darray_type<T> More...

typedef cow_darray< value_type, allocator_type, size_type, use_memmove, use_realloc, sec_mem >	cow_container_t

typedef cow_ro_iterator< storage_t, storage_ref_t, cow_container_t >	const_iterator
	Immutable, read-only const_iterator, lock-free, holding the current shared store reference until destruction. More...

typedef cow_rw_iterator< storage_t, storage_ref_t, cow_container_t >	iterator
	Mutable, read-write iterator, holding the write-lock and a store copy until destruction. More...

typedef bool(*	equal_comparator) (const value_type &a, const value_type &b)
	Generic value_type equal comparator to be user defined for e.g. More...

Public Member Functions
constexpr	cow_darray () noexcept
	Default constructor, giving almost zero capacity and zero memory footprint, but the shared empty jau::darray. More...

constexpr	cow_darray (size_type capacity, const float growth_factor=DEFAULT_GROWTH_FACTOR, const allocator_type &alloc=allocator_type())
	Creating an empty instance with initial capacity and other (default) properties. More...

constexpr	cow_darray (const storage_t &x)

constexpr	cow_darray (const storage_t &x, const float growth_factor, const allocator_type &alloc)

cow_darray &	operator= (const storage_t &x)
	Like std::vector::operator=(&), assignment, but copying from the underling jau::darray. More...

constexpr	cow_darray (storage_t &&x) noexcept

constexpr	cow_darray (storage_t &&x, const float growth_factor, const allocator_type &alloc) noexcept

cow_darray &	operator= (storage_t &&x)
	Like std::vector::operator=(&&), move, but taking the underling jau::darray. More...

constexpr_atomic	cow_darray (const cow_darray &x)
	Creates a new instance, copying all elements from the given array. More...

constexpr_atomic	cow_darray (const cow_darray &x, const float growth_factor, const allocator_type &alloc)
	Creates a new instance, copying all elements from the given array. More...

constexpr_atomic	cow_darray (const cow_darray &x, const size_type _capacity, const float growth_factor, const allocator_type &alloc)
	Creates a new instance with custom initial storage capacity, copying all elements from the given array. More...

constexpr_atomic cow_darray &	operator= (const cow_darray &x)
	Like std::vector::operator=(&), assignment. More...

constexpr_atomic	cow_darray (cow_darray &&x) noexcept

constexpr_atomic cow_darray &	operator= (cow_darray &&x) noexcept
	Like std::vector::operator=(&&), move. More...

constexpr	cow_darray (const size_type _capacity, const_iterator first, const_iterator last, const float growth_factor=DEFAULT_GROWTH_FACTOR, const allocator_type &alloc=allocator_type())
	Creates a new instance with custom initial storage capacity, copying all elements from the given const_iterator value_type range [first, last). More...

template<class InputIt >
constexpr	cow_darray (const size_type _capacity, InputIt first, InputIt last, const float growth_factor=DEFAULT_GROWTH_FACTOR, const allocator_type &alloc=allocator_type())
	Creates a new instance with custom initial storage capacity, copying all elements from the given template input-iterator value_type range [first, last). More...

template<class InputIt >
constexpr	cow_darray (InputIt first, InputIt last, const allocator_type &alloc=allocator_type())
	Creates a new instance, copying all elements from the given template input-iterator value_type range [first, last). More...

constexpr	cow_darray (std::initializer_list< value_type > initlist, const allocator_type &alloc=allocator_type())
	Create a new instance from an initializer list. More...

	~cow_darray () noexcept

constexpr size_type	max_size () const noexcept
	Returns `std::numeric_limits<difference_type>::max()` as the maximum array size. More...

constexpr std::recursive_mutex &	get_write_mutex () noexcept
	Returns this instances' recursive write mutex, allowing user to implement more complex mutable write operations. More...

constexpr_atomic storage_ref_t	copy_store ()
	Returns a new shared_ptr copy of the underlying store, i.e. More...

constexpr_atomic void	set_store (storage_ref_t &&new_store_ref) noexcept
	Replace the current store with the given instance, potentially acquired via jau::cow_darray::copy_store() and mutated while holding the jau::cow_darray::get_write_mutex() lock. More...

constexpr_atomic storage_ref_t	snapshot () const noexcept
	Returns the current snapshot of the underlying shared storage by reference. More...

constexpr const_iterator	cbegin () const noexcept
	Returns an jau::cow_ro_iterator to the first element of this CoW storage. More...

constexpr iterator	begin ()
	Returns an jau::cow_rw_iterator to the first element of this CoW storage. More...

const allocator_type &	get_allocator_ref () const noexcept

allocator_type	get_allocator () const noexcept

constexpr_atomic float	growth_factor () const noexcept
	Returns the growth factor. More...

constexpr_atomic size_type	capacity () const noexcept
	Like std::vector::empty(). More...

constexpr_atomic bool	empty () const noexcept
	Like std::vector::empty(). More...

constexpr_atomic size_type	size () const noexcept
	Like std::vector::size(). More...

void	reserve (size_type new_capacity)
	Like std::vector::reserve(), increases this instance's capacity to `new_capacity`. More...

constexpr_atomic void	clear () noexcept
	Like std::vector::clear(), but ending with zero capacity. More...

constexpr_atomic void	swap (cow_darray &x) noexcept
	Like std::vector::swap(). More...

constexpr_atomic void	pop_back () noexcept
	Like std::vector::pop_back(). More...

constexpr_atomic void	push_back (const value_type &x)
	Like std::vector::push_back(), copy. More...

constexpr_atomic void	push_back (value_type &&x)
	Like std::vector::push_back(), move. More...

template<typename... Args>
constexpr_atomic reference	emplace_back (Args &&... args)
	Like std::vector::emplace_back(), construct a new element in place at the end(). More...

template<class InputIt >
constexpr_atomic void	push_back (InputIt first, InputIt last)
	Like std::vector::push_back(), but appends the whole value_type range [first, last). More...

constexpr_atomic bool	push_back_unique (const value_type &x, equal_comparator comparator)
	Like std::vector::push_back(), but only if the newly added element does not yet exist. More...

constexpr_atomic int	erase_matching (const value_type &x, const bool all_matching, equal_comparator comparator)
	Erase either the first matching element or all matching elements. More...

constexpr_cxx20 std::string	toString () const noexcept

constexpr_cxx20 std::string	get_info () const noexcept

Static Public Attributes
constexpr static const float	DEFAULT_GROWTH_FACTOR = 1.618f
	Default growth factor using the golden ratio 1.618. More...

constexpr static const bool	uses_memmove = use_memmove

constexpr static const bool	uses_realloc = use_realloc

constexpr static const bool	uses_secmem = sec_mem

Detailed Description

template<typename Value_type, typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>
class jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >

Implementation of a Copy-On-Write (CoW) using jau::darray as the underlying storage, exposing lock-free read operations using SC-DRF atomic synchronization.

This class shall be compliant with C++ named requirements for Container.

The store is owned using a shared reference to the data structure, allowing its replacement on Copy-On-Write (CoW).

Writing to the store utilizes a mutex lock to avoid data races on the instances' write operations only, leaving read operations lock-free.
Write operations replace the store reference with a new instance using jau::sc_atomic_critical to synchronize with read operations.

Reading from the store is lock-free and accesses the store reference using jau::sc_atomic_critical to synchronizing with write operations.

Immutable storage const_iterators are supported via jau::cow_ro_iterator, which are constructed lock-free.
jau::cow_ro_iterator holds a snapshot retrieved via jau::cow_darray::snapshot() until its destruction.

Mutable storage iterators are supported via jau::cow_rw_iterator, which holds a copy of this CoW storage and locks its write mutex until jau::cow_rw_iterator::write_back() or its destruction.
After completing all mutable operations but before this iterator's destruction, the user might want to write back this iterators' storage to this CoW using jau::cow_rw_iterator::write_back().

Both, jau::cow_ro_iterator and jau::cow_rw_iterator are harmonized to work with jau::darray::const_iterator and jau::darray::iterator for all iterator based operations.

Index operation via ::operator[](size_t) or ::at(size_t) are not supported, since they would be only valid if value_type itself is a std::shared_ptr and hence prohibit the destruction of the object if mutating the storage, e.g. via jau::cow_darray::push_back().

Custom mutable write operations are also supported via jau::cow_darray::get_write_mutex(), jau::cow_darray::copy_store() and jau::cow_darray::set_store().
See example in jau::cow_darray::set_store()

To allow data-race free operations using iterators from a potentially mutated CoW, only one cow_darray::begin() const_iterator or iterator should be retrieved from this CoW and all further operations shall use its jau::cow_ro_iterator::size(), jau::cow_ro_iterator::begin() and jau::cow_ro_iterator::end()

or its respective variant from jau::cow_rw_iterator.

Non-Type Template Parameter use_memmove can be overriden by the user and has its default value std::is_trivially_copyable_v<Value_type>.
The default value has been chosen with care, see C++ Standard section 6.9 Types trivially copyable.
However, one can set use_memmove to true even without the value_type being trivially copyable, as long certain memory side-effects can be excluded (TBD).

Member Typedef Documentation

◆ allocator_type

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef Alloc_type jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::allocator_type

Definition at line 148 of file cow_darray.hpp.

◆ const_iterator

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef cow_ro_iterator<storage_t, storage_ref_t, cow_container_t> jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::const_iterator

Immutable, read-only const_iterator, lock-free, holding the current shared store reference until destruction.

Using jau::cow_darray::snapshot() at construction.

This iterator is the preferred choice if no mutations are made to the elements state itself, or all changes can be discarded after the iterator's destruction.
This avoids the costly mutex lock and storage copy of jau::cow_rw_iterator.
Also see jau::for_each_fidelity to iterate through in this good faith fashion.

See also: jau::cow_ro_iterator; jau::cow_ro_iterator::size(); jau::cow_ro_iterator::begin(); jau::cow_ro_iterator::end(); jau::for_each_fidelity; jau::cow_rw_iterator

Definition at line 181 of file cow_darray.hpp.

◆ const_pointer

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef const value_type* jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::const_pointer

Definition at line 143 of file cow_darray.hpp.

◆ const_reference

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef const value_type& jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::const_reference

Definition at line 145 of file cow_darray.hpp.

◆ cow_container_t

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef cow_darray<value_type, allocator_type, size_type, use_memmove, use_realloc, sec_mem> jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_container_t

Definition at line 160 of file cow_darray.hpp.

◆ darray_tag

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef bool jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::darray_tag

Used to determine whether this type is a darray or has a darray, see ::is_darray_type<T>

Definition at line 156 of file cow_darray.hpp.

◆ difference_type

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef std::make_signed<size_type>::type jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::difference_type

Definition at line 147 of file cow_darray.hpp.

◆ equal_comparator

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef bool(* jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::equal_comparator) (const value_type &a, const value_type &b)

Generic value_type equal comparator to be user defined for e.g.

jau::cow_darray::push_back_unique().

Parameters

a	one element of the equality test.
b	the other element of the equality test.

Returns: true if both are equal

Definition at line 921 of file cow_darray.hpp.

◆ iterator

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef cow_rw_iterator<storage_t, storage_ref_t, cow_container_t> jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::iterator

Mutable, read-write iterator, holding the write-lock and a store copy until destruction.

Using jau::cow_darray::get_write_mutex(), jau::cow_darray::copy_store() at construction
and jau::cow_darray::set_store() at destruction.

Due to the costly nature of mutable CoW resource management, consider using jau::cow_ro_iterator if elements won't get mutated or any changes can be discarded.

See also: jau::cow_rw_iterator; jau::cow_rw_iterator::size(); jau::cow_rw_iterator::begin(); jau::cow_rw_iterator::end(); jau::cow_ro_iterator

Definition at line 200 of file cow_darray.hpp.

◆ pointer

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef value_type* jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::pointer

Definition at line 142 of file cow_darray.hpp.

◆ reference

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef value_type& jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::reference

Definition at line 144 of file cow_darray.hpp.

◆ size_type

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef Size_type jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::size_type

Definition at line 146 of file cow_darray.hpp.

◆ storage_ref_t

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef std::shared_ptr<storage_t> jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::storage_ref_t

Definition at line 153 of file cow_darray.hpp.

◆ storage_t

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef darray<value_type, allocator_type, size_type, use_memmove, use_realloc, sec_mem> jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::storage_t

Definition at line 152 of file cow_darray.hpp.

◆ value_type

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

typedef Value_type jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::value_type

Definition at line 141 of file cow_darray.hpp.

Constructor & Destructor Documentation

◆ cow_darray() [1/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray ( )

inlineconstexprnoexcept

Default constructor, giving almost zero capacity and zero memory footprint, but the shared empty jau::darray.

Definition at line 218 of file cow_darray.hpp.

◆ cow_darray() [2/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray	(	size_type	capacity,
		const float	growth_factor = `DEFAULT_GROWTH_FACTOR`,
		const allocator_type &	alloc = `allocator_type()`
	)

inlineexplicitconstexpr

Creating an empty instance with initial capacity and other (default) properties.

Parameters

capacity	initial capacity of the new instance.
growth_factor	given growth factor
alloc	given allocator_type

Definition at line 229 of file cow_darray.hpp.

◆ cow_darray() [3/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray ( const storage_t & x )

inlineconstexpr

Definition at line 236 of file cow_darray.hpp.

◆ cow_darray() [4/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray	(	const storage_t &	x,
		const float	growth_factor,
		const allocator_type &	alloc
	)

inlineexplicitconstexpr

Definition at line 242 of file cow_darray.hpp.

◆ cow_darray() [5/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray ( storage_t && x )

inlineconstexprnoexcept

Definition at line 265 of file cow_darray.hpp.

◆ cow_darray() [6/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray	(	storage_t &&	x,
		const float	growth_factor,
		const allocator_type &	alloc
	)

inlineexplicitconstexprnoexcept

Definition at line 272 of file cow_darray.hpp.

◆ cow_darray() [7/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray ( const cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem > & x )

inline

Creates a new instance, copying all elements from the given array.

Capacity and size will equal the given array, i.e. the result is a trimmed array.

Parameters

x	the given cow_darray, all elements will be copied into the new instance.

Definition at line 305 of file cow_darray.hpp.

◆ cow_darray() [8/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray	(	const cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem > &	x,
		const float	growth_factor,
		const allocator_type &	alloc
	)

inlineexplicit

Creates a new instance, copying all elements from the given array.

Capacity and size will equal the given array, i.e. the result is a trimmed array.

Parameters

x	the given cow_darray, all elements will be copied into the new instance.
growth_factor	custom growth factor
alloc	custom allocator_type instance

Definition at line 325 of file cow_darray.hpp.

◆ cow_darray() [9/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray	(	const cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem > &	x,
		const size_type	_capacity,
		const float	growth_factor,
		const allocator_type &	alloc
	)

inlineexplicit

Creates a new instance with custom initial storage capacity, copying all elements from the given array.

Size will equal the given array.

Throws jau::IllegalArgumentException() if _capacity < x.size().

Parameters

x	the given cow_darray, all elements will be copied into the new instance.
_capacity	custom initial storage capacity
growth_factor	custom growth factor
alloc	custom allocator_type instance

Definition at line 349 of file cow_darray.hpp.

◆ cow_darray() [10/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray ( cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem > && x )

inlinenoexcept

Definition at line 388 of file cow_darray.hpp.

◆ cow_darray() [11/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray	(	const size_type	_capacity,
		const_iterator	first,
		const_iterator	last,
		const float	growth_factor = `DEFAULT_GROWTH_FACTOR`,
		const allocator_type &	alloc = `allocator_type()`
	)

inlineconstexpr

Creates a new instance with custom initial storage capacity, copying all elements from the given const_iterator value_type range [first, last).

Size will equal the range [first, last), i.e. size_type(last-first).

Throws jau::IllegalArgumentException() if _capacity < size_type(last - first).

Parameters

_capacity	custom initial storage capacity
first	const_iterator to first element of value_type range [first, last)
last	const_iterator to last element of value_type range [first, last)
growth_factor	custom growth factor
alloc	custom allocator_type instance

Definition at line 450 of file cow_darray.hpp.

◆ cow_darray() [12/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

template<class InputIt >

constexpr jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray	(	const size_type	_capacity,
		InputIt	first,
		InputIt	last,
		const float	growth_factor = `DEFAULT_GROWTH_FACTOR`,
		const allocator_type &	alloc = `allocator_type()`
	)

inlineexplicitconstexpr

Creates a new instance with custom initial storage capacity, copying all elements from the given template input-iterator value_type range [first, last).

Size will equal the range [first, last), i.e. size_type(last-first).

Throws jau::IllegalArgumentException() if _capacity < size_type(last - first).

Template Parameters

InputIt template input-iterator custom type

Parameters

_capacity	custom initial storage capacity
first	template input-iterator to first element of value_type range [first, last)
last	template input-iterator to last element of value_type range [first, last)
growth_factor	custom growth factor
alloc	custom allocator_type instance

Definition at line 472 of file cow_darray.hpp.

◆ cow_darray() [13/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

template<class InputIt >

constexpr jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray	(	InputIt	first,
		InputIt	last,
		const allocator_type &	alloc = `allocator_type()`
	)

inlineconstexpr

Creates a new instance, copying all elements from the given template input-iterator value_type range [first, last).

Size will equal the range [first, last), i.e. size_type(last-first).

Template Parameters

InputIt template input-iterator custom type

Parameters

first	template input-iterator to first element of value_type range [first, last)
last	template input-iterator to last element of value_type range [first, last)
alloc	custom allocator_type instance

Definition at line 489 of file cow_darray.hpp.

◆ cow_darray() [14/14]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cow_darray	(	std::initializer_list< value_type >	initlist,
		const allocator_type &	alloc = `allocator_type()`
	)

inlineconstexpr

Create a new instance from an initializer list.

Parameters

initlist	initializer_list.
alloc	allocator

Definition at line 501 of file cow_darray.hpp.

◆ ~cow_darray()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::~cow_darray ( )

inlinenoexcept

Definition at line 508 of file cow_darray.hpp.

Member Function Documentation

◆ begin()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr iterator jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::begin ( )

inlineconstexpr

Returns an jau::cow_rw_iterator to the first element of this CoW storage.

Acquiring this mutable iterator has considerable costs attached, read remarks in jau::cow_rw_iterator.

Use jau::cow_rw_iterator::end() on this returned iterator to retrieve the end iterator in a data-race free fashion.

Returns: jau::cow_darray::iterator of type jau::cow_rw_iterator

See also: jau::cow_rw_iterator; jau::cow_rw_iterator::size(); jau::cow_rw_iterator::begin(); jau::cow_rw_iterator::end()

Definition at line 659 of file cow_darray.hpp.

Here is the caller graph for this function:

◆ capacity()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic size_type jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::capacity ( ) const

inlinenoexcept

Like std::vector::empty().

This read operation is lock-free.

Returns

Definition at line 692 of file cow_darray.hpp.

◆ cbegin()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr const_iterator jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::cbegin ( ) const

inlineconstexprnoexcept

Returns an jau::cow_ro_iterator to the first element of this CoW storage.

This method is the preferred choice if the use case allows, read remarks in jau::cow_ro_iterator.

Use jau::cow_ro_iterator::end() on this returned const_iterator to retrieve the end const_iterator in a data-race free fashion.

Returns: jau::cow_darray::const_iterator of type jau::cow_ro_iterator

See also: jau::cow_ro_iterator; jau::cow_ro_iterator::size(); jau::cow_ro_iterator::begin(); jau::cow_ro_iterator::end(); jau::for_each_fidelity

Definition at line 636 of file cow_darray.hpp.

Here is the caller graph for this function:

◆ clear()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic void jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::clear ( )

inlinenoexcept

Like std::vector::clear(), but ending with zero capacity.

This write operation uses a mutex lock and is blocking this instances' write operations.

Definition at line 751 of file cow_darray.hpp.

Here is the caller graph for this function:

◆ copy_store()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic storage_ref_t jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::copy_store ( )

inline

Returns a new shared_ptr copy of the underlying store, i.e.

using a new copy-constructed vectore.

See example in jau::cow_darray::set_store()

This special operation uses a mutex lock and is blocking this instances' write operations only.

See also: jau::cow_darray::get_write_mutex(); jau::cow_darray::copy_store(); jau::cow_darray::set_store()

Definition at line 550 of file cow_darray.hpp.

◆ emplace_back()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

template<typename... Args>

constexpr_atomic reference jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::emplace_back ( Args &&... args )

inline

Like std::vector::emplace_back(), construct a new element in place at the end().

Constructs the element at the end() using placement new.

size will be increased by one.

Parameters

args	arguments to forward to the constructor of the element

Definition at line 865 of file cow_darray.hpp.

◆ empty()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic bool jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::empty ( ) const

inlinenoexcept

Like std::vector::empty().

This read operation is lock-free.

Definition at line 704 of file cow_darray.hpp.

◆ erase_matching()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic int jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::erase_matching	(	const value_type &	x,
		const bool	all_matching,
		equal_comparator	comparator
	)

inline

Erase either the first matching element or all matching elements.

This write operation uses a mutex lock and is blocking this instances' write operations only.

Examples

    cow_darray<Thing> list;
    int count = list.erase_matching(element, true,
                   [](const Thing &a, const Thing &b) -> bool { return a == b; });
    ...
    static jau::cow_darray<Thing>::equal_comparator thingRefEqComparator =
                 [](const std::shared_ptr<Thing> &a, const std::shared_ptr<Thing> &b) -> bool { return *a == *b; };
    ...
    cow_darray<std::shared_ptr<Thing>> listOfRefs;
    int count = listOfRefs.erase_matching(element, false, thingRefEqComparator);

Parameters

x	the value to be added at the tail, if not existing yet.
all_matching	if true, erase all matching elements, otherwise only the first matching element.
comparator	the equal comparator to return true if both given elements are equal

Returns: number of erased elements

Definition at line 986 of file cow_darray.hpp.

Here is the caller graph for this function:

◆ get_allocator()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

allocator_type jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::get_allocator ( ) const

inlinenoexcept

Definition at line 670 of file cow_darray.hpp.

◆ get_allocator_ref()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

const allocator_type& jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::get_allocator_ref ( ) const

inlinenoexcept

Definition at line 665 of file cow_darray.hpp.

◆ get_info()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_cxx20 std::string jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::get_info ( ) const

inlinenoexcept

Definition at line 1018 of file cow_darray.hpp.

Here is the caller graph for this function:

◆ get_write_mutex()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr std::recursive_mutex& jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::get_write_mutex ( )

inlineconstexprnoexcept

Returns this instances' recursive write mutex, allowing user to implement more complex mutable write operations.

See example in jau::cow_darray::set_store()

See also: jau::cow_darray::get_write_mutex(); jau::cow_darray::copy_store(); jau::cow_darray::set_store()

Definition at line 534 of file cow_darray.hpp.

◆ growth_factor()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic float jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::growth_factor ( ) const

inlinenoexcept

Returns the growth factor.

Definition at line 679 of file cow_darray.hpp.

Here is the caller graph for this function:

◆ max_size()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr size_type jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::max_size ( ) const

inlineconstexprnoexcept

Returns std::numeric_limits<difference_type>::max() as the maximum array size.

We rely on the signed difference_type for pointer arithmetic, deducing ranges from iterator.

Definition at line 519 of file cow_darray.hpp.

◆ operator=() [1/4]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic cow_darray& jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::operator= ( const cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem > & x )

inline

Like std::vector::operator=(&), assignment.

This write operation uses a mutex lock and is blocking this instances' write operations only.

Definition at line 368 of file cow_darray.hpp.

◆ operator=() [2/4]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

cow_darray& jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::operator= ( const storage_t & x )

inline

Like std::vector::operator=(&), assignment, but copying from the underling jau::darray.

This write operation uses a mutex lock and is blocking this instances' write operations only.

Definition at line 254 of file cow_darray.hpp.

◆ operator=() [3/4]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic cow_darray& jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::operator= ( cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem > && x )

inlinenoexcept

Like std::vector::operator=(&&), move.

This write operation uses a mutex lock and is blocking both cow_vector instance's write operations.

Definition at line 413 of file cow_darray.hpp.

◆ operator=() [4/4]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

cow_darray& jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::operator= ( storage_t && x )

inline

Like std::vector::operator=(&&), move, but taking the underling jau::darray.

This write operation uses a mutex lock and is blocking this instances' write operations only.

Definition at line 285 of file cow_darray.hpp.

◆ pop_back()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic void jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::pop_back ( )

inlinenoexcept

Like std::vector::pop_back().

This write operation uses a mutex lock and is blocking this instances' write operations only.

Definition at line 787 of file cow_darray.hpp.

◆ push_back() [1/3]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic void jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::push_back ( const value_type & x )

inline

Like std::vector::push_back(), copy.

This write operation uses a mutex lock and is blocking this instances' write operations only.

Parameters

x	the value to be added at the tail.

Definition at line 810 of file cow_darray.hpp.

Here is the caller graph for this function:

◆ push_back() [2/3]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

template<class InputIt >

constexpr_atomic void jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::push_back	(	InputIt	first,
		InputIt	last
	)

inline

Like std::vector::push_back(), but appends the whole value_type range [first, last).

This write operation uses a mutex lock and is blocking this instances' write operations only.

Template Parameters

InputIt foreign input-iterator to range of value_type [first, last)

Parameters

first	first foreign input-iterator to range of value_type [first, last)
last	last foreign input-iterator to range of value_type [first, last)

Definition at line 895 of file cow_darray.hpp.

◆ push_back() [3/3]

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic void jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::push_back ( value_type && x )

inline

Like std::vector::push_back(), move.

This write operation uses a mutex lock and is blocking this instances' write operations only.

Definition at line 835 of file cow_darray.hpp.

◆ push_back_unique()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic bool jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::push_back_unique	(	const value_type &	x,
		equal_comparator	comparator
	)

inline

Like std::vector::push_back(), but only if the newly added element does not yet exist.

This write operation uses a mutex lock and is blocking this instances' write operations only.

Examples

    static jau::cow_darray<Thing>::equal_comparator thingEqComparator =
                 [](const Thing &a, const Thing &b) -> bool { return a == b; };
    ...
    jau::cow_darray<Thing> list;

    bool added = list.push_back_unique(new_element, thingEqComparator);
    ...
    cow_darray<std::shared_ptr<Thing>> listOfRefs;
    bool added = listOfRefs.push_back_unique(new_element,
                   [](const std::shared_ptr<Thing> &a, const std::shared_ptr<Thing> &b) -> bool { return *a == *b; });

Parameters

x	the value to be added at the tail, if not existing yet.
comparator	the equal comparator to return true if both given elements are equal

Returns: true if the element has been uniquely added, otherwise false

Definition at line 948 of file cow_darray.hpp.

Here is the caller graph for this function:

◆ reserve()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

void jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::reserve ( size_type new_capacity )

inline

Like std::vector::reserve(), increases this instance's capacity to new_capacity.

Only creates a new storage and invalidates iterators if new_capacity is greater than the current jau::darray::capacity().

This write operation uses a mutex lock and is blocking this instances' write operations only.

Definition at line 733 of file cow_darray.hpp.

◆ set_store()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic void jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::set_store ( storage_ref_t && new_store_ref )

inlinenoexcept

Replace the current store with the given instance, potentially acquired via jau::cow_darray::copy_store() and mutated while holding the jau::cow_darray::get_write_mutex() lock.

This is a move operation, i.e. the given new_store_ref is invalid on the caller side after this operation.
User shall pass the store via std::move()

    cow_darray<std::shared_ptr<Thing>> list;
    ...
    {
        std::lock_guard<std::recursive_mutex> lock(list.get_write_mutex());
        std::shared_ptr<std::vector<std::shared_ptr<Thing>>> snapshot = list.copy_store();
        ...
        some fancy mutation
        ...
        list.set_store(std::move(snapshot));
    }

Above functionality is covered by jau::cow_rw_iterator, see also jau::cow_rw_iterator::write_back()

Parameters

new_store_ref the user store to be moved here, replacing the current store.

See also: jau::cow_darray::get_write_mutex(); jau::cow_darray::copy_store(); jau::cow_darray::set_store(); jau::cow_rw_iterator; jau::cow_rw_iterator::write_back()

Definition at line 587 of file cow_darray.hpp.

◆ size()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic size_type jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::size ( ) const

inlinenoexcept

Like std::vector::size().

This read operation is lock-free.

Definition at line 716 of file cow_darray.hpp.

Here is the caller graph for this function:

◆ snapshot()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic storage_ref_t jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::snapshot ( ) const

inlinenoexcept

Returns the current snapshot of the underlying shared storage by reference.

Note that this snapshot will be outdated by the next (concurrent) write operation.
The returned referenced vector is still valid and not mutated, but does not represent the current content of this cow_darray instance.

This read operation is lock-free.

Definition at line 610 of file cow_darray.hpp.

Here is the caller graph for this function:

◆ swap()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_atomic void jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::swap ( cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem > & x )

inlinenoexcept

Like std::vector::swap().

This write operation uses a mutex lock and is blocking both cow_darray instance's write operations.

Definition at line 767 of file cow_darray.hpp.

◆ toString()

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr_cxx20 std::string jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::toString ( ) const

inlinenoexcept

Definition at line 1007 of file cow_darray.hpp.

Here is the caller graph for this function:

Member Data Documentation

◆ DEFAULT_GROWTH_FACTOR

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr static const float jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::DEFAULT_GROWTH_FACTOR = 1.618f

staticconstexpr

Default growth factor using the golden ratio 1.618.

Definition at line 133 of file cow_darray.hpp.

◆ uses_memmove

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr static const bool jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::uses_memmove = use_memmove

staticconstexpr

Definition at line 135 of file cow_darray.hpp.

◆ uses_realloc

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr static const bool jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::uses_realloc = use_realloc

staticconstexpr

Definition at line 136 of file cow_darray.hpp.

◆ uses_secmem

template<typename Value_type , typename Alloc_type = jau::callocator<Value_type>, typename Size_type = jau::nsize_t, bool use_memmove = std::is_trivially_copyable_v<Value_type>, bool use_realloc = std::is_base_of_v<jau::callocator<Value_type>, Alloc_type>, bool sec_mem = false>

constexpr static const bool jau::cow_darray< Value_type, Alloc_type, Size_type, use_memmove, use_realloc, sec_mem >::uses_secmem = sec_mem

staticconstexpr

Definition at line 137 of file cow_darray.hpp.

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

/usr/local/projects/direct_bt/jaulib/include/jau/cow_darray.hpp

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ allocator_type

◆ const_iterator

◆ const_pointer

◆ const_reference

◆ cow_container_t

◆ darray_tag

◆ difference_type

◆ equal_comparator

◆ iterator

◆ pointer

◆ reference

◆ size_type

◆ storage_ref_t

◆ storage_t

◆ value_type

Constructor & Destructor Documentation

◆ cow_darray() [1/14]

◆ cow_darray() [2/14]

◆ cow_darray() [3/14]

◆ cow_darray() [4/14]

◆ cow_darray() [5/14]

◆ cow_darray() [6/14]

◆ cow_darray() [7/14]

◆ cow_darray() [8/14]

◆ cow_darray() [9/14]

◆ cow_darray() [10/14]

◆ cow_darray() [11/14]

◆ cow_darray() [12/14]

◆ cow_darray() [13/14]

◆ cow_darray() [14/14]

◆ ~cow_darray()

Member Function Documentation

◆ begin()

◆ capacity()

◆ cbegin()

◆ clear()

◆ copy_store()

◆ emplace_back()

◆ empty()

◆ erase_matching()

◆ get_allocator()

◆ get_allocator_ref()

◆ get_info()

◆ get_write_mutex()

◆ growth_factor()

◆ max_size()

◆ operator=() [1/4]

◆ operator=() [2/4]

◆ operator=() [3/4]

◆ operator=() [4/4]

◆ pop_back()

◆ push_back() [1/3]

◆ push_back() [2/3]

◆ push_back() [3/3]

◆ push_back_unique()

◆ reserve()

◆ set_store()

◆ size()

◆ snapshot()

◆ swap()

◆ toString()

Member Data Documentation

◆ DEFAULT_GROWTH_FACTOR

◆ uses_memmove

◆ uses_realloc

◆ uses_secmem