Echelon LNS - Manual (Page 333)

LNS Programmer's Guide 319
functions will be executed by an internal LNS thread, as opposed to the thread that
instantiated the Object Server. While it is usually more efficient to use direct callback,
especially when writing a monitor and control application, or an application that you
expect to receive a large number of events, you should be aware that this turns the
application into a multi-threaded application. This means that these handler functions
must not call back into LNS, and the client application must be written to properly deal
with multiple threads executing concurrently. Note that this applies to all events, not
just monitoring events.
For more specific information on multi-threading with COM, consult the documentation
for the development environment you are using with LNS.
Avoiding Memory Leaks with LNS
If you are using a Visual C++ based development environment to create an LNS
application that receives LNS events, you need to make special considerations in some
situations to avoid memory leaks. Due to Microsoft's COM referencing standards, objects
returned as elements in an event are owned by LNS, not by the application that received
the event. As a result, the client application needs to increment the reference count for
each object received in an event handler in order to keep a copy of that object after the
LNS event handler has returned.
Before discussing objects passed by event handlers further, consider how objects that are
returned when you invoke an LNS method or access an LNS property are handled.
Objects returned by properties and methods are owned by the client application, and
LNS increments the reference count for these objects automatically as copies of the
objects are created and destroyed. Although LNS increments the object's reference count
before passing it to the client application, it is up to the client to call Release() on the
object before removing it from memory. This decrements the reference count. Different
COM client wrappers such as MFC and ATL may handle this differently.
It is important to realize that how objects are freed after being passed through the event
mechanism is different than for objects returned through method invocation or property
access. LNS does not increment the reference count for objects passed to an application
via events. If you want your application to keep an object returned via an event longer
than the duration of the event-handling function, you need to call
AddRef()
on that
object, so that the object will not be removed from memory when the event-handler exits.
You must also call
Release()
when you are done with the object, to ensure that it is
properly removed from memory.
All client applications must follow COM reference count rules and properly manage their
reference counts in this fashion, so that LNS knows when to appropriately destroy an
object. Failure to properly call
AddRef()
when copying an object returned by an event
will cause access violations in the client application, as it will hold a pointer to an object
that has already been deleted. Failure to properly call
Release()
when removing an
object from memory that was returned by an event will result in memory leaks in the
client application or in LNS.
The Visual Basic runtime environment manages object reference counts automatically,
so you do not need to be concerned with memory leaks as a result of receiving LNS events
if you are using Visual Basic. For more information on COM reference count rules,
consult the Visual Studio documentation.