CnC
 All Classes Namespaces Functions Variables Typedefs Enumerator Friends Groups Pages
Public Types | Public Member Functions
item_collection< Tag, Item, Tuner > Class Template Reference

An item collection is a mapping from tags to items. More...

List of all members.

Public Types

typedef Tag tag_ype
 the tag type

Public Member Functions

template<class Derived >
 item_collection (context< Derived > &ctxt, const std::string &name, const Tuner &tnr)
 constructor which registers collection with given context
void set_max (size_t mx)
 Declares the maxium tag value.
void put (const Tag &tag, const Item &item)
 make copies of the item and the tag and store them in the collection.
void get (const Tag &tag, Item &item) const
 get an item
bool unsafe_get (const Tag &tag, Item &item) const
 try to get an item and store it in given object (non-blocking)
const_iterator begin () const
 returns begin() as in STL containers
const_iterator end () const
 returns end() as in STL containers
void unsafe_reset ()
 removes all of the item instances from the collection
size_t size ()
 returns number of elements in collection
bool empty ()
 returns true if size()==0, false otherwise

Detailed Description

template<typename Tag, typename Item, typename Tuner = hashmap_tuner>
class CnC::item_collection< Tag, Item, Tuner >

An item collection is a mapping from tags to items.

Tag and Item must provide copy and default constructors and the assigment operator.

Th last template argument is an optional tuner. The tuner provides tuning hints, such as the type of the data store or information about its use in distributed environments. Most importantly it tells the runtime and compiler which type of data store it should use. By default that's a hash-map (hashmap_tuner). For non default-supported tag types (e.g. those that are not convertable into size_t) a suitable cnc_hash template specialization must be provided. If in addition your type does not support std::equal_to you also need to specialize cnc_equal. For the vector-based data store (vector_tuner) that's not necessary, but the tag-type must then be convertible to and from size_t.

See also:
CnC::item_tuner for more information.

The CnC runtime will make a copy of your item when it is 'put' into the item_collection. The CnC runtime will delete the copied item copy once the get-count reaches 0 (or, if no get-count was provided, once the collection is destroyed). If the item-type is a pointer type, the runtime will not delete the memory the item points to. If you store pointeres, you have to care for the appropriate garbage collection, e.g. you might consider using smart pointers.

Definition at line 230 of file cnc.h.


Constructor & Destructor Documentation

item_collection ( context< Derived > &  ctxt,
const std::string &  name,
const Tuner &  tnr 
)

constructor which registers collection with given context

Parameters:
ctxtthe context this collection belongs to
namean optional name, used for debug output and tracing
tnra tuner object which must persist throughout the lifetime of the step-collection by default a default-constructed tuner will be used.

Member Function Documentation

const_iterator begin ( ) const

returns begin() as in STL containers

Note:
iteration through collections is not thread safe; use it only between calls to CnC::context::wait() and putting tags
const_iterator end ( ) const

returns end() as in STL containers

Note:
iteration through collections is not thread safe; use it only between calls to CnC::context::wait() and putting tags
void get ( const Tag &  tag,
Item &  item 
) const

get an item

Parameters:
tagthe tag identifying the item
itemreference to item to store result in
Exceptions:
DataNotReadythrows exception if data not yet available.
void put ( const Tag &  tag,
const Item &  item 
)

make copies of the item and the tag and store them in the collection.

Parameters:
tagthe tag identifying the item
itemthe item to be copied and stored
void set_max ( size_t  mx)

Declares the maxium tag value.

Must be called prior to accessing the collection if the data store is a vector. Useful only for dense tag-spaces.

Parameters:
mxthe largest tag-value ever used for this collection
bool unsafe_get ( const Tag &  tag,
Item &  item 
) const

try to get an item and store it in given object (non-blocking)

Attention:
This method is unsafe: you can create non-deterministic results if you decide to to perform semantically relevant actions if an item is unavailable (returns false)

If the item is unavailable, it does not change item. Make sure you call flush_gets() after last call to this method (of any item collection) within a step. In any case, you must check the return value before accessing the item.

Parameters:
tagthe tag identifying the item
itemreference to item to store result in
Returns:
true if item is available
Exceptions:
DataNotReadymight throw exception if data not available (yet)
void unsafe_reset ( )

removes all of the item instances from the collection

Note:
not thread-safe, to be called in safe state only (between program start or calling context::wait() and putting the first tag or item).

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