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

---

Member Typedef Documentation

typedef base_coll_type::callback_type callback_type

callback type for item-collections.

See also:

register_callback

Definition at line 341 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:

ctxt	the context this collection belongs to
name	an optional name, used for debug output and tracing
tnr	a 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:

tag	the tag identifying the item
item	reference to item to store result in

Exceptions:

DataNotReady

throws exception if data not yet available.

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

void put	(	const Tag &	tag,
		const Item &	item
	)

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

Parameters:

tag	the tag identifying the item
item	the 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:

mx	the 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:

tag	the tag identifying the item
item	reference to item to store result in

Returns:

true if item is available

Exceptions:

DataNotReady

might 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:

• cnc.h