Archon::Utilities::RefMap< T > Struct Template Reference

A map between object references on the "inside" and object indices on the "outside". More...

#include <archon/util/ref.H>

Inheritance diagram for Archon::Utilities::RefMap< T >:

[legend]Collaboration diagram for Archon::Utilities::RefMap< T >:

[legend]List of all members.

Public Member Functions
unsigned long	get (Ref< T > r, bool create=true)
	If the specified reference is found in the map then its corresponding key is returned, If the reference is not found and 'create' is false then the null key is returned, otherwise an association for the reference is added to the map and the new unique key is returned.
Ref< T >	operator() (unsigned long key) const
	Returns the reference associated with the specified key or the null if the key is null or there is no reference associated with the key.
void	remove (unsigned long key, unsigned long transCount=0)
	Removes the specified key and its reference association from the map.
void	remove (Ref< T > r)
	Removes the specified reference and its key association from the map.
void	clear (vector< Ref< T > > *remains=0)

---

Detailed Description

template<typename T>
struct Archon::Utilities::RefMap< T >

A map between object references on the "inside" and object indices on the "outside".

This is an important brick in an object based API which needs to be very resistant to misbehaving applications.

The reason one wants to use indices rather than pointers on the "outside" is that it is much too costly to validate pointers on their way in. That is, to check that the pointers refer properly to objects and that access to those objects are granted to the application in question.

Indices, on the other hand can be validated in constant time. This, of cource, is only reasonable if the indices are kept small (concentrated near zero). Otherwise they becomes equivalent to pointers. In this reference map, the indices are kept small.

Another very important feature of this object reference map is that it allows for applications to keep "inside" objects alive through usage counting without risking memory leak after death of the application. This is achieved by maintaining a seperate "outside" usage count in the map. This usage count is 1 for a newly created map entry, and is incremented for each additional map operation (call to the "get" method) on the same object reference.

The application can choose between two ways of releasing objects when they are no longer needed. Either the application will keep track of each individually aquired object key or it will keep track of keys on an object basis. In the first case the application is advised to call the "remove" method (with transCount = 1) once for each aquired key when that key is abandoned - even when several of these keys refer to tha same object. In the latter case the application is advised to call the "remove" method with transCount = 0 (meaning: release all outside usage counts) once for each mapped object.

Naturally we cannot trust applications the job of releasing precisely as many counted references as it aquired or even releasing anything at all. Fortunately we can choose destroy or clear the entire map at any time, and when we do that, all the mapped references will be released regardless of the current outside usage counts.

Of cource an application can still mix up object indices and thereby access a different object than what was expected, but as long as the map at all times is kept down to the subset of "inside" objects to whom the application explicitly has been granted access, we can maintain a reasonable level of security and robustness.

This map offers very fast (constant time) translation of keys to refs, and reasonably fast translation from refs to keys (that is faster than sequential search). Further more it offers strict determination of whether a key is in the map as a side effect of the translation from key to ref. It also has the property of using small intergers as keys. That is, new keys will always be smaller that the currently largest one if such a key is free. Otherwise it will be one plus the currently largest one.

All methods are thread-safe.

Todo:

Do we really need to place this map in this file?? Currently it is here because it needs to be a friend of Ref since it needs to access refInc and refDec directly since it wants to prevent the overhead in expanding a vector of Refs.

What can be done to solve this matter?? One thing that could be done, is to use plain arrays instead, and then manually resize by using swap(Ref, Ref). We might even want to encapsulate it into a new special RefVector class.

Definition at line 875 of file ref.H.

---

Member Function Documentation

template<typename T> unsigned long Archon::Utilities::RefMap< T >::get (  Ref< T >  r, bool  create = true )  [inline]

If the specified reference is found in the map then its corresponding key is returned, If the reference is not found and 'create' is false then the null key is returned, otherwise an association for the reference is added to the map and the new unique key is returned. As a special case, if the null reference is passed, then the null key is always returned. Definition at line 896 of file ref.H. Referenced by Archon::X3D::SAI::Session::createApplicationScene(), Archon::X3D::SAI::Session::loadApplicationScene(), and Archon::X3D::SAI::Session::node2id().

template<typename T> Ref<T> Archon::Utilities::RefMap< T >::operator() (  unsigned long  key  )  const [inline]

Returns the reference associated with the specified key or the null if the key is null or there is no reference associated with the key. Todo: It is completely unacceptable that we do not get an exceptional signal when the passed key is not found in the map. We should react specifically to the situation where the client attempts to use illegal object keys. The same goes for 'remove'. Definition at line 914 of file ref.H.

template<typename T> void Archon::Utilities::RefMap< T >::remove (  unsigned long  key, unsigned long  transCount = 0 )  [inline]

Removes the specified key and its reference association from the map. Parameters: transCount  Number of translations from ref to key to remove. Zero indicates 'all'. Reimplemented from Archon::Utilities::RefMapBase. Definition at line 927 of file ref.H. Referenced by Archon::X3D::SAI::Session::disposeBatch(), Archon::X3D::SAI::Session::disposeContext(), and Archon::X3D::SAI::Session::disposeNode().

---

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

• archon/util/ref.H

---