CnC
Public Types | Public Member Functions | List of all members
item_collection< Tag, Item, Tuner > Class Template Reference

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

Public Types

typedef Tag tag_type
 the tag type
 
typedef Item data_type
 the data/item type
 
typedef base_coll_type::callback_type callback_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 More...
 
void set_max (size_t mx)
 Declares the maxium tag value. More...
 
void put (const Tag &tag, const Item &item)
 make copies of the item and the tag and store them in the collection. More...
 
void get (const Tag &tag, Item &item) const
 get an item More...
 
bool unsafe_get (const Tag &tag, Item &item) const
 try to get an item and store it in given object (non-blocking) More...
 
const_iterator begin () const
 returns begin() as in STL containers More...
 
const_iterator end () const
 returns end() as in STL containers More...
 
void unsafe_reset ()
 removes all of the item instances from the collection More...
 
size_t size ()
 returns number of elements in collection
 
bool empty ()
 returns true if size()==0, false otherwise
 
void on_put (callback_type *cb)
 

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 57 of file cnc.h.

Member Typedef Documentation

◆ callback_type

typedef base_coll_type::callback_type callback_type

callback type for item-collections.

See also
register_callback

Definition at line 346 of file cnc.h.

Constructor & Destructor Documentation

◆ item_collection()

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

◆ begin()

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

◆ end()

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

◆ get()

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.

◆ on_put()

void on_put ( callback_type cb)

Call this to register a on-put-callback for the item-collection. When registered, callback.on_put( tag, item ) gets called when an item was put successfully. The call is blocking, e.g. the triggering/calling "put" will not return to its caller until the callback has terminated.

The provided object will be deleted when the collection is deleted.

In distCnC, the callback will be executed on the (first) process returned by tuner::consumed_on (which defaults to execution on the process which puts the item).

See also
graph for more details, in particular about thread-safety issues
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).
not needed for regular CnC

◆ put()

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

◆ set_max()

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

◆ unsafe_get()

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)

◆ unsafe_reset()

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: