diff --git a/containers_cpp/include/embb/containers/internal/object_pool-inl.h b/containers_cpp/include/embb/containers/internal/object_pool-inl.h index c0f4bde..9458a55 100644 --- a/containers_cpp/include/embb/containers/internal/object_pool-inl.h +++ b/containers_cpp/include/embb/containers/internal/object_pool-inl.h @@ -83,7 +83,7 @@ ReturningTrueIterator::operator!=(const self_type& rhs) { template bool ObjectPool:: IsContained(const Type &obj) const { - if ((&obj < &objects_array_[0]) || + if ((&obj < &objects_array_[0]) || (&obj > &objects_array_[value_pool_size_ - 1])) { return false; } else { diff --git a/containers_cpp/include/embb/containers/lock_free_tree_value_pool.h b/containers_cpp/include/embb/containers/lock_free_tree_value_pool.h index b6f99e0..b33e074 100644 --- a/containers_cpp/include/embb/containers/lock_free_tree_value_pool.h +++ b/containers_cpp/include/embb/containers/lock_free_tree_value_pool.h @@ -285,8 +285,13 @@ class LockFreeTreeValuePool { * by it. However, usually one wants to guarantee a minimal capacity. The * count of elements, that must be given to the pool when to guarantee \c * capacity elements is computed using this function. + * + * \return count of indices the pool has to be initialized with */ - static size_t GetMinimumElementCountForGuaranteedCapacity(size_t capacity); + static size_t GetMinimumElementCountForGuaranteedCapacity( + size_t capacity + /**< [IN] count of indices that shall be guaranteed */); + ); /** * Destructs the pool. diff --git a/containers_cpp/include/embb/containers/object_pool.h b/containers_cpp/include/embb/containers/object_pool.h index 5583e5f..889f5cc 100644 --- a/containers_cpp/include/embb/containers/object_pool.h +++ b/containers_cpp/include/embb/containers/object_pool.h @@ -114,6 +114,7 @@ class ObjectPool { bool IsContained(const Type &obj) const; int GetIndexOfObject(const Type &obj) const; Type* AllocateRaw(); + public: /** * Constructs an object pool with capacity \c capacity. diff --git a/containers_cpp/include/embb/containers/wait_free_array_value_pool.h b/containers_cpp/include/embb/containers/wait_free_array_value_pool.h index d174e8c..5a6bfda 100644 --- a/containers_cpp/include/embb/containers/wait_free_array_value_pool.h +++ b/containers_cpp/include/embb/containers/wait_free_array_value_pool.h @@ -39,12 +39,30 @@ namespace containers { * \ingroup CPP_CONCEPT * \{ * \par Description - * A value pool is a fixed-size multiset of elements, where each element has a - * unique index. The elements cannot be modified and are given at construction - * time (by providing first/last iterators). A value pool provides two - * operations: \c Allocate and \c Free. \c Allocate removes an element from the - * pool, and \c Free returns an element to the pool. It is only allowed to - * free elements that have previously been allocated. + * A value pool is a multi-set of elements, where each element has a unique, + * continuous (starting with 0) index. The elements cannot be modified and are + * given at construction time by providing first/last iterators. + * + * \par + * A value pool provides two primary operations: \c Allocate and \c Free. \c + * Allocate allocates an element/index "pair" (index via return, element via + * reference parameter) from the pool, and \c Free returns an element/index pair + * to the pool. To guarantee linearizability, \c element is not allowed to be + * modified between \c Allocate and \c Free. It is only allowed to free elements + * that have previously been allocated. The \c Allocate function does not + * guarantee an order on which indices are allocated. The count of elements that + * can be allocated with \c Allocate might be smaller than the count of + * elements, the pool is initialized with. This might be because of + * implementation details and respective concurrency effects: for example, if + * indices are managed within a queue, one has to protect queue elements from + * concurrency effects (reuse and access). As long as a thread potentially + * accesses a node (and with that an index), the respective index cannot not be + * given out to the user, even if being logically not part of the pool anymore. + * However, the user might want to guarantee a certain amount of indices to the + * user. Therefore, the static \c GetMinimumElementCountForGuaranteedCapacity + * method is used. The user passes the count of indices to this method, that + * shall be guaranteed by the pool. The method returns the count on indices, the + * pool has to be initialized with in order to guarantee this count on indices. * * \par Requirements * - Let \c Pool be the pool class @@ -54,6 +72,7 @@ namespace containers { * - Let \c i, j be forward iterators supporting \c std::distance. * - Let \c c be an object of type \c Type& * - Let \c e be a value of type \c int + * - Let \c f be a value of type \c int * * \par Valid Expressions * @@ -72,7 +91,7 @@ namespace containers { * the bottom element. The bottom element cannot be stored in the pool, it * is exclusively used to mark empty cells. The pool initially contains * \c std::distance(i, j) elements which are copied during construction from - * the range \c [i, j). A concrete class satisfying the value pool concept + * the range \c [i, j]. A concrete class satisfying the value pool concept * might provide additional template parameters for specifying allocators. * * @@ -80,9 +99,10 @@ namespace containers { * \code{.cpp} Allocate(c) \endcode * \c int * - * Gets an element from the pool. Returns -1, if no element is available, - * i.e., the pool is empty. Otherwise, returns the index of the element in - * the pool. The value of the pool element is written into reference \c c. + * Allocates an element/index "pair" from the pool. Returns -1, if no + * element is available, i.e., the pool is empty. Otherwise, returns the + * index of the element in the pool. The value of the pool element is + * written into parameter reference \c c. * * * @@ -93,6 +113,15 @@ namespace containers { * \c Allocate. For each allocated element, \c Free must be called exactly * once. * + * + * \code{.cpp} GetMinimumElementCountForGuaranteedCapacity(f) + * \endcode + * \c void + * Static method, returns the count of indices, the user has to + * initialize the pool with in order to guarantee a count of \c f elements + * (irrespective of concurrency effects). + * + * * * * \} @@ -154,8 +183,12 @@ class WaitFreeArrayValuePool { * by it. However, usually one wants to guarantee a minimal capacity. The * count of elements, that must be given to the pool when to guarantee \c * capacity elements is computed using this function. + * + * \return count of indices the pool has to be initialized with */ - static size_t GetMinimumElementCountForGuaranteedCapacity(size_t capacity); + static size_t GetMinimumElementCountForGuaranteedCapacity( + size_t capacity + /**< [IN] count of indices that shall be guaranteed */); /** * Destructs the pool. @@ -183,7 +216,7 @@ class WaitFreeArrayValuePool { * Returns an element to the pool. * * \note The element must have been allocated with Allocate(). - * + * * \waitfree * * \see CPP_CONCEPTS_VALUE_POOL