Summary
The XStream® HDVR® SDK provides a reference counting mechanism to allocate and deallocate memory, ensuring that unreferenced objects are automatically deallocated. When the C++ API is in use, utility methods allocate XStream HDVR class objects to ensure that they are tracked by the XStream HDVR reference counting mechanism. When the Java/.NET APIs are in use, memory allocation and reference counting is automatically implemented by the Java/.NET language framework. Other utility methods are provided to manage server side memory resources from the client.
When the C++ API is in use, the main XStream HDVR class objects are allocated by several utility methods. The names of these classes begin with an 'I', such as IPanAdaptor, IRenderQueue, IVertexCallListContext, etc. Most XStream HDVR class objects are allocated by the ILibrary::CreateObject() method. This method takes two parameters. The first is an input parameter that takes the address of a GUID object specifying the type of class to allocate. The second is an output parameter that is a pointer set to the address of the newly allocated class object. Some XStream HDVR classes are allocated by dedicated utility methods in the IServerContext class. These methods take parameters that customize class-specific options for different XStream HDVR classes. Calls to the conventional C++ new and delete operators allocate and deallocate XStream HDVR structures that are used as input or output parameters for methods of the main XStream HDVR classes.
IServerContext *pServer = NULL;
pLibrary->CreateObject(&CLSID_ServerContext, &pServer);
pServer->Connect(address, port, &logError, &serverResponse);
IRenderEngineContext *pRenderEngine = NULL;
pServer->CreateRenderEngine(&pRenderEngine, RECID_PAR);
IVertexCallListContext *pVertexCallList = NULL;
pServer->CreateVertexCallList(&pVertexCallList);
When using the Java/.NET APIs, most XStream HDVR class objects are allocated with calls to the conventional Java/.NET new operator. The constructors for these classes manage the proper allocation of these classes. Some XStream HDVR classes are allocated with dedicated utility methods in the hdrcServerContext class. These methods take parameters that customize class-specific options for different XStream HDVR classes. Deallocation of these objects is handled by the built-in Java/C# memory manager.
hdrcServerContext serverContext;
serverContext = new hdrcServerContext(host, port);
hdrcRenderEngineContext renderEngine;
renderEngine = serverContext.createRenderEngine(hdrcDefines.RENDER_ENGINE_ID_PAR);
hdrcVertexCallListContext vertexCallList;
vertexCallList = serverContext.createVertexCallList();
hdrcServerContext serverContext;
serverContext = new hdrcServerContext(host, port);
hdrcRenderEngineContext renderEngine;
renderEngine = serverContext.createRenderEngine(hdrcDefines.__Fields.RENDER_ENGINE_ID_PAR);
hdrcVertexCallListContext vertexCallList;
vertexCallList = serverContext.createVertexCallList();
Reference Counting and Deallocation
When the C++ API is used, XStream HDVR class objects that are allocated with the ILibrary::CreateObject() method or utility methods in the IServerContext class are tracked with a reference counting mechanism. When an object is allocated, its reference count is set to 1. Whenever the client application adds a reference to an existing object, its IncRef() method should be called. When a reference to an object is removed, its DecRef() method should be called. An object is automatically deallocated when its reference count reaches 0.
The C++ delete operator should never be used to deallocate XStream HDVR class objects that have been allocated by utility methods.
IRenderEngineContext *pRenderEngine = NULL;
// pRenderEngine referece count is set to 1 at creation.
pServer->CreateRenderEngine(&pRenderEngine, RECID_PAR);
// Add a reference to pRenderEngine, reference count = 2.
pRenderEngine->IncRef();
pRenderEngineReference = pRenderEngine;
// Remove reference and decrement reference count to 1.
pRenderEngineReference->DecRef();
pRenderEngineReference = NULL;
// pRenderEngine reference set to 0, client side object will be deallocated.
pRenderEngine->DecRef();
pRenderEngine = NULL;
When using the Java/.NET APIs, XStream HDVR class objects are tracked by the reference counting mechanisms built into the Java and .NET/C# languages. There is no need to call reference counting methods.
hdrcRenderEngineContext renderEngine = NULL;
// renderEngine referece count is set to 1 at creation.
renderEngine = server.createRenderEngine(hdrcDefines.RENDER_ENGINE_ID_PAR);
// Add a reference to pRenderEngine, reference count = 2.
renderEngineReference = renderEngine;
// Remove reference, reference count is decremented to 1.
pRenderEngineReference = NULL;
// renderEngine reference set to 0, client side object will be deallocated.
renderEngine = NULL;
When an XStream HDVR class object is allocated by the ILibrary::CreateObject() method, or utility methods in the IServerContext class, a corresponding object is usually created in the server application. All HDVR class objects with a corresponding server side representation contain the word 'context' in their name. The client side object serves as a placeholder for the server side object, which XStream HDVR have a much larger memory footprint (such as the IVolumeDataContex and IOctreeContext objects). The reference counting mechanisms described above apply only to class objects in the client application. When a client side object's reference count reaches 0, only the client side object is deallocated. To deallocate the server side object, call its ReleaseSessionResources() method. This method signals the server to deallocate resources associated with that context object. All XStream HDVR context objects have a corresponding ReleaseSessionResources() method. Failure to call the appropriate ReleaseSessionResources() method can cause memory leaks in the server application. Note that terminating a XStream HDVR client session by disconnecting from the server causes the server application to automatically release all memory associated with that client session. In this case it is not necessary to call the ReleaseSessionResources() method for objects associated with the terminated session.
// We are done with this render engine so release server side resources.
pRenderEngine->ReleaseSessionResources()
// pRenderEngine reference set to 0, client side object will be deallocated.
pRenderEngine->DecRef();
pRenderEngine = NULL;
Whenever a HDVR® class object is allocated a corresponding object is usually created in the server application. All HDVR class objects with a corresponding server side representation contain the word 'context' in their name. The client side object serves as a placeholder for the server side object, which can have a much larger memory footprint (such as the hdrcVolumeDataContex and hdrcOctreeContext objects). The reference counting mechanisms described above apply only to class objects in the client application. When a client side object's reference count reaches 0, only the client side object is deallocated. To deallocate the server side object, call its releaseSessionResources() method. This method signals the server to deallocate resources associated with that context object. All HDVR® context objects have a corresponding releaseSessionResources() method. Failure to call the appropriate releaseSessionResources() method can cause memory leaks in the server application. Note that terminating a XStream HDVR client session by disconnecting from the server causes the server application to automatically release all memory associated with that client session. In this case it is not necessary to call the releaseSessionResources() method for objects associated with the terminated session.
// We are done with this render engine so release server side resources.
renderEngine.releaseSessionResources()
// renderEngine reference set to 0, client side object will be deallocated.
pRenderEngine = NULL;
