Common Mistakes

This section lists some common mistakes that occur when adding USS support to classes. The compile and link-time errors received depend on the compiler used. The errors reported by one particular compiler are presented here. For brevity, the code examples are not presented here, but they are provided in the directory <ospace/stream/examples>.

Providing duplicate IDs-If two classes have the same ID, an os_streaming_toolkit_error is thrown with code duplicate_class , as in the example mistake1.cpp. Because this condition commonly occurs during static initialization, an error message is also displayed to cerr .


os_streaming_toolkit_error: duplicate class
        Class with ID 1001 defined for both Y and X
Check rtti/binary stream macros.

Forgetting to specify the base class-If the base class is not specified in either the OS_STREAMABLE_n or the OS_NO_FACTORY_STREAMABLE_n macro, an os_streaming_toolkit_error is thrown with code os_type_mismatch , such as the following example, or erroneous results can be reported. Refer to the mistake2.cpp example.


Wrote to the stream :
1  2
Caught os_streaming_toolkit_error:
        Attempt to read wrong type.
        type_mismatch: Cannot cast from Y to X,
            check rtti/binary stream macro.

Forgetting to provide binary stream source macro-A link-time error, such as the following, is reported if the binary stream macro is not placed in the source file. Refer to the mistake3.cpp example.


Undefined                       first referenced
 symbol                             in file
os_class_of_aux(X*)            mistake3.o
ld: fatal: Symbol referencing errors. No output written to mistake3
*** Error code 1
make: Fatal error: Command failed for target `mistake3'
Exit 1

Providing the wrong binary stream source macro (Case 1)-An os_streaming_toolkit_error is thrown with code uninitialized_class , if the source macro OS_NO_FACTORY_STREAMABLE_n is used instead of the OS_STREAMABLE_n macro, for concrete classes with public default constructors. Refer to the mistake4.cpp example.


Wrote to the stream :
1
Caught stream error:
      Incorrect or no RTTI/Binary Stream macro is supplied for class.
      uninitialized_class: Allocate/Deallocate functions not
      available for class X, check rtti/binary stream macro.

Refer to the "Add a Macro to a Source File" section of this chapter for use limitations of concrete classes without public default constructors.

Providing the wrong binary stream source macro (Case 2)-For abstract classes or classes with no default constructors, a compile-time error like the following is reported if the OS_STREAMABLE_n macro is used instead of the OS_NO_FACTORY_STREAMABLE_n macro. Refer to the mistake5.cpp example.


"../../../ospace/rtti/regmacro.h", line 112: Error: Cannot create a variable for abstract class X.
1 Error(s) detected.
*** Error code 1
make: Fatal error: Command failed for target `mistake5.o'
Exit 1

Forgetting to provide binary stream header macro-A compile-time error is reported if the OS_STREAM_OPERATORS macro is not specified in the class header file. Refer to the mistake6.cpp example. Compiling this example yields the following output.


mistake6.cpp", line 54: Error: The operation "os_bstream << X" is illegal.
1 Error(s) detected.
*** Error code 1
make: Fatal error: Command failed for target `mistake6.o'
Exit 1

Reading/Writing data members out of sequence-If data members are read out of sequence, an os_streaming_toolkit_error is thrown with code type_mismatch . Refer to the mistake7.cpp example. The following is output from this example.


Wrote to the stream :
1  A
Caught stream error:
        Attempt to read wrong type.
        type_mismatch: Tried to read char but got int

Reading a different number of data members than were written-If more data members are read than written, or if more data members are written than read, an os_streaming_toolkit_error is thrown with code framing_error . Refer to the mistake8.cpp example. The following is output from this example when more data members are read than written.


Wrote to the stream :
1  A
Caught stream error:
        An object was not written in the same way it was read.
        framing_error: Tried to read char but got end of object

Reading from an IOStream device instead of the os_bstream-Both IOStream and os_bstream objects understand streaming operators. Therefore, programs that stream to or from the IOStream object, instead of the os_bstream object, can compile. The runtime behavior of a reader that expects binary data may be a core dump, a memory allocation failure, or a runtime type mismatch.
Using an object reference and assuming the binary streaming system will treat it as an object pointer-In C++, object references act as pointers with different syntax semantics. However, C++ type matching rules give object references the appearance of objects when using os_bstream . Therefore, os_bstream creates a separate copy of an object when using a C++ reference instead of creating an object pointer. This action causes duplicate objects when reading in the stream data.
Streaming enumerations to a binary stream-Since enum values are custom data types, the Universal Streaming Service cannot provide builtin support for enum values. To persist an enum value, it must be explicitly casted to another primitive type like int . Ensure that the casted type can hold the entire contents of the enum value; for example, casting an enum value of 1000 to a char results in data loss.
Streaming unions to a binary stream-Due to platform portability restrictions, you cannot stream a union using the Universal Streaming Service. The contents of the union can be persisted manually by user code, but you must ensure that the union is streamed in a platform-independent manner.