ichthyo/LUMIERA.clone
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
LUMIERA.clone/src/lib/linked-elements.hpp
Ichthyostega 685a9b84ee Library: replace boost::noncopyable by our own library solution 
Benefits
 - get rid of yet another pervasive Boost dependency
 - define additional more fine grained policies (move only, clonable)
2018-03-24 05:35:13 +01:00

592 lines
18 KiB
C++
Raw Blame History

/*
LINKED-ELEMENTS.hpp - configurable intrusive single linked list template
Copyright (C) Lumiera.org
2012, Hermann Vosseler <Ichthyostega@web.de>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
/** @file linked-elements.hpp
** Intrusive single linked list with optional ownership.
** This helper template allows to attach a number of tightly integrated
** elements with low overhead. Typically, these elements are to be attached
** once and never changed. Optionally, elements can be created using a
** custom allocation scheme; the holder might also take ownership. These
** variations in functionality are controlled by policy templates.
**
** The rationale for using this approach is
** - variable number of elements
** - explicit support for polymorphism
** - no need to template the holder on the number of elements
** - no heap allocations (contrast this to using std::vector)
** - clear and expressive notation at the usage site
** - convenient access through Lumiera Forward Iterators
** - the need to integrate tightly with a custom allocator
**
** @note this linked list container is \em intrusive and thus needs the help
** of the element type, which must provide a pointer member \c next.
** Consequently, each such node element can't be member in
** multiple collections at the same time
** @note as usual, any iterator relies on the continued existence and
** unaltered state of the container. There is no sanity check.
** @warning this container is deliberately not threadsafe
** @warning be sure to understand the implications of taking ownership:
** When adding an existing node element (by pointer) to a LinkedElements
** list which takes ownership, the list will attempt to destroy or de-allocate
** this node element when going out of scope.
**
** @see LinkedElements_test
** @see llist.h
** @see ScopedCollection
** @see itertools.hpp
*/
#ifndef LIB_LINKED_ELEMENTS_H
#define LIB_LINKED_ELEMENTS_H
#include "lib/error.hpp"
#include "lib/nocopy.hpp"
#include "lib/iter-adapter.hpp"
#include "lib/util.hpp"
#include <boost/static_assert.hpp>
namespace lib {
namespace error = lumiera::error;
using error::LUMIERA_ERROR_INDEX_BOUNDS;
using util::unConst;
namespace linked_elements { ///< allocation policies for the LinkedElements list container
/**
* Policy for LinkedElements: taking ownership
* and possibly creating heap allocated Nodes
*/
struct OwningHeapAllocated
{
typedef void* CustomAllocator;
/** this policy discards elements
* by deallocating them from heap
*/
template<class X>
void
destroy (X* elm)
{
delete elm;
}
/** this policy creates new elements
* simply by heap allocation */
template<class TY>
TY&
create ()
{
return *new TY();
}
template<class TY, typename A1>
TY& //____________________________________________
create (A1 a1) ///< create object of type TY, using 1-arg ctor
{
return *new TY(a1);
}
template< class TY
, typename A1
, typename A2
>
TY& //____________________________________________
create (A1 a1, A2 a2) ///< create object of type TY, using 2-arg ctor
{
return *new TY(a1,a2);
}
template< class TY
, typename A1
, typename A2
, typename A3
>
TY& //____________________________________________
create (A1 a1, A2 a2, A3 a3) ///< create object of type TY, using 3-arg ctor
{
return *new TY(a1,a2,a3);
}
template< class TY
, typename A1
, typename A2
, typename A3
, typename A4
>
TY& //____________________________________________
create (A1 a1, A2 a2, A3 a3, A4 a4) ///< create object of type TY, using 4-arg ctor
{
return *new TY(a1,a2,a3,a4);
}
template< class TY
, typename A1
, typename A2
, typename A3
, typename A4
, typename A5
>
TY& //____________________________________________
create (A1 a1, A2 a2, A3 a3, A4 a4, A5 a5) ///< create object of type TY, using 5-arg ctor
{
return *new TY(a1,a2,a3,a4,a5);
}
};
/**
* Policy for LinkedElements: never create or destroy
* any elements, only allow to add already existing nodes.
* @note any added node needs to provide a \c next pointer
* field, which is used ("intrusively") for managing
* the list datastructure. But besides that, the
* node element won't be altered or discarded
* in any way.
*/
struct NoOwnership
{
typedef void* CustomAllocator;
/** this policy doesn't take ownership
* and thus never discards anything
*/
void
destroy (void*)
{
/* does nothing */
}
};
#ifdef LIB_ALLOCATION_CLUSTER_H
/**
* Policy for LinkedElements: especially using a
* lib::AllocationCluster instance for creating
* new node elements. It is mandatory to pass
* this cluster instance to the ctor of any
* LinkedElements list using this policy
* @note AllocationCluster always de-allocates
* any created elements in one sway.
*/
struct UseAllocationCluster
{
typedef AllocationCluster& CustomAllocator;
CustomAllocator cluster_;
explicit
UseAllocationCluster (CustomAllocator clu)
: cluster_(clu)
{ }
/** while this policy indeed implies creating and owing
* new objects, the AllocationCluster doesn't support
* discarding individual instances. All created objects
* within the cluster will be bulk de-allocated
* when the cluster as such goes out of scope.
*/
void
destroy (void*)
{
/* does nothing */
}
template<class TY>
TY& //__________________________________________
create () ///< place object of type TY, by default ctor
{
return cluster_.create<TY>();
}
template<class TY, typename A1>
TY& //___________________________________________
create (A1 a1) ///< place object of type TY, using 1-arg ctor
{
return cluster_.create<TY> (a1);
}
template< class TY
, typename A1
, typename A2
>
TY& //___________________________________________
create (A1 a1, A2 a2) ///< place object of type TY, using 2-arg ctor
{
return cluster_.create<TY> (a1,a2);
}
template< class TY
, typename A1
, typename A2
, typename A3
>
TY& //___________________________________________
create (A1 a1, A2 a2, A3 a3) ///< place object of type TY, using 3-arg ctor
{
return cluster_.create<TY> (a1,a2,a3);
}
template< class TY
, typename A1
, typename A2
, typename A3
, typename A4
>
TY& //___________________________________________
create (A1 a1, A2 a2, A3 a3, A4 a4) ///< place object of type TY, using 4-arg ctor
{
return cluster_.create<TY> (a1,a2,a3,a4);
}
};
#endif //(End)if lib/allocation-cluster.hpp was included
}//(END)namespace linked_elements
/**
* Intrusive single linked list, possibly taking ownership of node elements.
* Additional elements can be pushed (prepended) to the list; element access
* is per index number (slow) or through an Lumiera Forward Iterator traversing
* the linked list. There is no support for changing the list contents aside
* of discarding any element in the list.
*
* The allocation and ownership related behaviour is controlled by a policy class
* provided as template parameter. When this policy supports creation of new
* elements, these might be created and prepended in one step.
*/
template
< class N ///< node class or Base/Interface class for nodes
, class ALO = linked_elements::OwningHeapAllocated
>
class LinkedElements
: util::NonCopyable
, ALO
{
N* head_;
public:
~LinkedElements ()
{
clear();
}
LinkedElements ()
: head_(0)
{ }
/** @param allo custom allocator or memory manager
* to be used by the policy for creating and
* discarding of node elements
*/
explicit
LinkedElements (typename ALO::CustomAllocator allo)
: ALO(allo)
, head_(0)
{ }
/** creating a LinkedElements list in RAII-style:
* @param elements iterator to provide all the elements
* to be pushed into this newly created collection
* @note any exception while populating the container
* causes already created elements to be destroyed
*/
template<class IT>
LinkedElements (IT elements)
: head_(0)
{
try {
pushAll(elements);
}
catch(...)
{
WARN (progress, "Failure while populating LinkedElements list. "
"All elements will be discarded");
clear();
throw;
} }
/** @note EX_FREE */
void
clear()
{
while (head_)
{
N* elm = head_;
head_ = head_->next;
try {
ALO::destroy(elm);
}
ERROR_LOG_AND_IGNORE (progress, "Clean-up of element in LinkedElements list")
}
}
/** convenience shortcut to add all the elements
* yielded by the given Lumiera Forward Iterator
* @note EX_SANE
*/
template<class IT>
void
pushAll (IT elements)
{
for ( ; elements; ++elements )
push (*elements);
}
/** accept the given element and prepend it to the list of elements;
* depending on the allocation policy, this might imply taking ownership
* @note EX_STRONG
*/
template<typename TY>
TY&
push (TY& elm)
{
elm.next = head_;
head_ = &elm;
return elm;
}
template< class TY >
TY& //_________________________________________
pushNew () ///< add object of type TY, using 0-arg ctor
{
return push (ALO::template create<TY>());
}
template< class TY
, typename A1
>
TY& //_________________________________________
pushNew (A1 a1) ///< add object of type TY, using 1-arg ctor
{
return push (ALO::template create<TY>(a1));
}
template< class TY
, typename A1
, typename A2
>
TY& //_________________________________________
pushNew (A1 a1, A2 a2) ///< add object of type TY, using 2-arg ctor
{
return push (ALO::template create<TY>(a1,a2));
}
template< class TY
, typename A1
, typename A2
, typename A3
>
TY& //_________________________________________
pushNew (A1 a1, A2 a2, A3 a3) ///< add object of type TY, using 3-arg ctor
{
return push (ALO::template create<TY>(a1,a2,a3));
}
template< class TY
, typename A1
, typename A2
, typename A3
, typename A4
>
TY& //_________________________________________
pushNew (A1 a1, A2 a2, A3 a3, A4 a4) ///< add object of type TY, using 4-arg ctor
{
return push (ALO::template create<TY>(a1,a2,a3,a4));
}
template< class TY
, typename A1
, typename A2
, typename A3
, typename A4
, typename A5
>
TY& //_________________________________________
pushNew (A1 a1, A2 a2, A3 a3, A4 a4, A5 a5) ///< add object of type TY, using 5-arg ctor
{
return push (ALO::template create<TY>(a1,a2,a3,a4,a5));
}
/* === Element access and iteration === */
N&
operator[] (size_t index) const
{
N* p = head_;
while (p && index)
{
p = p->next;
--index;
}
if (!p || index)
throw error::Logic ("Attempt to access element beyond the end of LinkedElements list"
, LUMIERA_ERROR_INDEX_BOUNDS);
else
return *p;
}
/** @warning traverses to count the elements */
size_t
size () const
{
uint count=0;
N* p = head_;
while (p)
{
p = p->next;
++count;
}
return count;
}
bool
empty () const
{
return !head_;
}
private:
/**
* Iteration is just following the single linked list.
* We encapsulate this simple pointer into a dedicated marker type
* to ease the handling and mixing of iterators and const iterators.
* (Explanation: IterationState depends on our type parameters...)
*/
struct IterationState
{
N* node;
IterationState(N* p=0)
: node(p)
{ }
/* ==== internal callback API for the iterator ==== */
/** Iteration-logic: switch to next position
* @warning assuming the given node pointer belongs to this collection.
* actually this is never checked; also the given node might
* have been deallocated in the meantime.
*/
void
iterNext()
{
node = node->next;
}
/** Iteration-logic: detect iteration end. */
bool
checkPoint() const
{
return bool(node);
}
N&
yield() const
{
REQUIRE (node);
return * unConst(this)->node;
}
friend bool
operator== (IterationState const& il, IterationState const& ir)
{
return il.node == ir.node;
}
};
public:
typedef IterStateWrapper< N, IterationState> iterator;
typedef IterStateWrapper<const N, IterationState> const_iterator;
iterator begin() { return iterator (head_); }
const_iterator begin() const { return const_iterator (head_); }
iterator end () { return iterator(); }
const_iterator end () const { return const_iterator(); }
};
} // namespace lib
#endif
Reference in a new issue View git blame Copy permalink