Tools.h++ Manual

104011 Tandem Computers Incorporated 3-7

which returns a pointer to a collection allocated off the heap with members

satisfying some selection criterion. Again, you are responsible for deleting this

collection when you are done with it.

Both of these exceptions are documented in detail in Chapter 21, “Class

Reference.”

3.5 Information ﬂow

Generally, with the Tools.h++ libraries, information ﬂows into a function via its

arguments and out through a return value. Most functions do not modify their

arguments. Indeed, if you see an argument being passed as a “const

reference”, i.e., as follows:

void foo(const RWCString& a)

or (of course) by value, then you can be conﬁdent that the argument will not be

modiﬁed. However, if an argument is passed as a non-const reference (this is

rare) then there is the possibility that the function will modify it.

If an argument is being passed in as a pointer, then there is the strong

possibility that the function will retain a copy of the pointer. This is typical of

the collection classes:

RWOrdered::insert(RWCollectable*);

This is to remind you that the collection will be retaining a pointer to the object

after the function returns

3.6 Multi-thread safe

When compiled with the appropriate option (see the release notes for your

compiler) Tools.h++ is multi-thread safe. What this means is that all functions

behave in a multi-threaded environment as in a single-threaded environment

provided that the application program either takes care to avoid sharing of

individual objects between threads or takes care to perform locking around

1. An alternative design strategy would have been to pass objects that are to be inserted into a collection by

reference (as done by The NIH Classes). We rejected this approach for two reasons: it looks too similar to

pass-by-value (making it easy for the programmer to forget about the retained reference) and it becomes too

easy to store a reference to a stack-based variable.