The ObjAsm programming model supports three fundamental build-in features:
- Error propagation
- Data and object streaming
- Data or object conglomeration with collections
All objects have a variable inherited from Primer called pOwner that can point to an object that is responsible for it. This data member is usually set during initialization and does not change during the life cycle of the object.
To implement the error propagation, 2 additional data members were added to Primer object:
DefineVariable dErrorCode, DWORD, 0
DefineVariable pErrorCaller, POINTER, NULL
and additionally 3 methods to handle them
VirtualMethod ErrorReport, POINTER, DWORD
VirtualMethod ErrorSet, DWORD
Supposing that a method has detected an error condition, it sets the error code using the ErrorReport method and advises to its owner that something has gone wrong. In this situation, the owner can react taking a corrective action or it can pass the error signalization to its own owner. This behaviour is repeated until some object can handle the error situation or the top most owner was reached.
The ErrorSet method was used by the ErrorReport method to simply set the error code without propagation.
The ErrorClear method was used to walk the error path back to the first caller, resetting the error code.
Streaming is a widely known technique used to store data into streams. This also known as persistence.
A stream is a generic name of a storage medium, like a disk file, a memory block or even a communication port.
The goal of using a generic object for all types of possible storages is to handle all of them in the same way. Generic code to load and store the object data has the big advantage that the code of the storage stream can be made later or can be redirected to a different stream type.
To get streaming capabilities, an object has to derive from Streamable. This object defines two abstract methods, Load and Store.
These methods must be redefined to provide data persistence. These methods are automatically called when the stream invokes the Put or Get methods to load or store the object data on the stream.
ObjAsm defines several Stream objects like DiskStream, MemoryStream, etc. with different specializations. The use of each stream type depends on the specific purpose.
Persistence is implemented in the ObjAsm model using serialization. This technique enables to write the data sequentially and read them back in the same sequence. For most data types, this is trivial, but for pointers and references, which may be loaded in a different process, they are completely meaningless. ObjAsm provides a special mechanism to restore these elements in a proper way to get back their original functionality.
One of the most repeated situation is the requirement to bundle data or even objects together. For simple data structures, arrays appear to be the best solution, but for complex structures with different sizes, or when the array dimension size cannot be determined a priory, a better solution must be found. Collections are the answer!
Collections are flexible and highly optimized objects that can handle all types of structures and objects at runtime. If necessary, you can increase your storage capacity up to a predetermined limit. Automatic object destruction is also provided when the collection members are no longer needed.
ObjAsm offers different types of collections that specialize in different tasks. The basic form of a collection can handle objects as described above. A SortedCollection handles the items applying a sorting strategy. A StrCollection is a specialized derived object that handles strings. Finally, a DataCollection specializes in data structures that do not require special handling, such as objects.
All types of collections can be customized at runtime overwriting the dynamic methods DestroyItem, GetItem and PutItem.