Rogue Wave banner
Previous fileTop of DocumentContentsIndex pageNext file
Essential Tools Module User's Guide

2.4 Common Functionality Among Classes

This section describes issues that affect almost every Essential Tools Module class, including member functions, memory allocation, information flow, multithread safety, indexing, and finding the module version number.

2.4.1 Common Member Functions

Whatever their category, all classes have similar programming interfaces. This section highlights their common member functions.

2.4.1.1 Persistence Functions

The Essential Tools Module uses the following member functions to store an object of type ClassName to and from an RWFile, and to and from the Rogue Wave virtual streams facility, and to restore it later:

Class RWFile, which encapsulates ANSI-C file I/O, saves objects in binary format. The result is efficient storage and retrieval to files. For more information on RWFile, see Chapter 11 and the Essential Tools Module Reference Guide.

Classes RWvistream and RWvostream are abstract base classes used by the Rogue Wave virtual streams facility. The final output format is determined by the specializing class. For example, RWpistream and RWpostream are two classes that derive from RWvistream and RWvostream, respectively. They store and retrieve objects using a portable ASCII format. The results can be transferred between different operating systems. These classes are discussed in more detail in Chapter 5 and the Essential Tools Module Reference Guide.

You can decide whether to store to RWFiles or to Rogue Wave streams. Storing to RWFiles gives you speed, but limits portability of results to the host machine and operating system. Storing to Rogue Wave streams is not as fast, but you get several specializing classes that provide other useful features. These features include a highly portable format between different machines and XDR stream encapsulation for distributed computations.

2.4.1.2 Store Size Functions

The following common member functions return the number of bytes of secondary storage necessary to store an object of type ClassName to an RWFile:

The member functions use the function:

The above member functions are good for storing objects using classes RWFileManager and RWBTreeOnDisk. For objects that inherit from RWCollectable, the second variant recursiveStoreSize() can calculate the number of bytes used in a recursive store. The variant uses the function:

You can use class RWAuditStreamBuffer in conjunction with any stream to count the number of bytes that pass through the buffer. RWAuditStreamBuffer thus provides the same functionality for streams that the StoreSize member functions (discussed above) provide for files. For more information on class RWAuditStreamBuffer, see the Essential Tools Module Reference Guide.

2.4.1.3 Stream I/O Functions

The overloaded left-shift operator <<, taking an ostream object as its first argument, will print the contents of an object in human-readable form. Conversely, the overloaded right-shift operator >>, taking an istream object as its first argument, will read and parse an object from the stream in a human-understandable format.

The overloaded left-shift and right-shift operators contrast with the persistence operators:

Although the persistence shift operators may store and restore to and from a stream, they will not necessarily do so in a form that could be called "human-readable."

2.4.1.4 Comparison Functions

Finally, most classes have comparison and equality member functions:

and their logical operator counterparts:

2.4.2 Memory Allocation and Deallocation

When an object is allocated off the heap, who is responsible for deleting it? With some libraries, ownership can be a problem.

Most of the Rogue Wave classes take a very simple approach: if you allocate something off the heap, then you are responsible for deallocating it. If the Rogue Wave library allocates something off the heap, then it is responsible for deallocating it.

There are two exceptions for creation of objects. The first exception involves the operators:

These operators restore an object inheriting from RWCollectable from an RWFile or RWvistream, respectively. They return a pointer to an object allocated off the heap: you are responsible for deleting it.

The second exception is member function:

This function 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.

There is also an exception for object deletion: As a service, many of the collection classes provide a method, clearAndDestroy(), which will remove all pointers from the collection and delete each. Even with clearAndDestroy(), however, it is still your responsibility to know that it is safe to delete all the pointers in that collection.

These methods are documented in detail in the Essential Tools Module Reference Guide.

2.4.3 Information Flow

With the Rogue Wave libraries, information generally flows into a function via its arguments and out through a return value. Most functions do not modify their arguments. Indeed, if an argument is passed by value or as a const reference:

you can be confident that the argument will not be modified. However, if an argument is passed as a non-const reference, you may find that the function will modify it.

If an argument is passed in as a pointer, there is the strong possibility that the function will retain a copy of the pointer. This is typical of the collection classes:

The function retains a copy of the pointer to remind you that the collection will be retaining a pointer to the object after the function returns.

An alternative design strategy would be to pass objects that are to be inserted into a collection by reference, as in The NIH Classes. We rejected this approach for two reasons: it looks so similar to pass-by-value that the programmer could forget about the retained reference, and it becomes too easy to store a reference to a stack-based variable.

2.4.4 Multithread Safety

Rogue Wave defines three levels of thread safety, depending on how a class is implemented. These include unsafe, safe, and multithread safe, as described below.

2.4.4.1 Assigning Thread Safety Levels to Classes and Libraries

When a class or library is assigned a thread safety level, it is possible that one or more individual members will differ from the classification of the whole. In the event that a member of a class or library is less thread-safe than its parent, this difference will be clearly documented. In addition, we'll make every effort to document any thread-safe exceptions in a summary discussion of the class or library.

2.4.4.2 Thread Safety in the Essential Tools Module

Unless otherwise specified, all classes in the Essential Tools Module are assigned a thread safety level of MT-1. All of these classes perform sufficient internal locking on global and static data to ensure that they behave correctly when used in a multithreaded environment; however they also require that the user provide external locking around operations on objects that are shared between multiple threads.

2.4.5 Indexing

Indexes have type size_t, an unsigned integral type defined by your compiler, usually in <stddef.h>. Because size_t is unsigned, it allows 2n minus one, where n is the number of bits the size_t type has on your system.

Invalid indexes are signified by the special value RW_NPOS, defined in
<rw/defs.h>.

2.4.6 Version

When programming, you may need to know the specific version number of the Essential Tools Module to perform certain operations. This number is given by the macro RWTOOLS, expressed as a hexadecimal number. For example, version 1.2.3 would be 0x123. This can be used for conditional compilations.

If the version is needed at run time, you can find it via the function rwToolsVersion(), declared in header file <rw/tooldefs.h>.



Previous fileTop of DocumentContentsIndex pageNext file

©2004 Copyright Quovadx, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.