The guarded streams synchronize a group of streaming operations in a multithreaded environment. They require the first of the guarded stream elements to be a synchronized stream because they use its internal mutex to ensure that all operations invoked on the guarded stream are part of a single synchronized group of operations.

The guarded streams are usually temporary objects that are created using a manipulator in a group of insertion operations. For instance, if an object os is a handle to a chain of streaming elements whose first element is a synchronized stream, then the following code creates a temporary guarded stream that ensures that all the following insertions are synchronized.

The rwGuard manipulator creates a temporary guarded stream that locks its next streaming element’s (a synchronized stream) internal mutex. The insertions that follow are made onto the temporary guarded stream, which simply forwards them to the synchronized stream’s next streaming element. After the last insertion is carried out, the temporary guarded stream object is destroyed, which releases its next streaming element’s internal mutex.

The guarded streams can also be created by using their public static make() function, in which case they retain the lock on their next streaming element until they are destroyed. If the next streaming element used to construct a guarded stream is not a synchronized stream, then the guarded stream does not have any effect. It forwards only a request to its next streaming element.

The guarded stream classes for the input streams are named RWGuarded{TYPE}InputStreamImp, and the guarded stream classes for the output streams are named RWGuarded{TYPE}OutputStreamImp, where {TYPE} is one of the following:

Your application manipulates the concrete stream classes only when they are created. After creation, the concrete stream classes are manipulated through their corresponding handle classes.