Here's the text from an Objects slide that is part of a DirectFB usage
presentation I put together (and will hopefully someday find time to update the
Wiki with):
DirectFB API uses a basic component object model
+ API functionality is partitioned into interfaces which are used
to access and control the functionality of the associated underlying
object.
+ Each object maintains its own lifetime and destroys itself after all
outstanding references to it via its interfaces have been released.
+ Every interface has AddRef() and Release() functions for explicitly
incrementing and decrementing an object's reference count.
+ Calling the various DirectFB GetXXX() or CreateXYZ() functions
throughout the API each results in an implicit reference count
increase - as if AddRef() on the interface had been called.
+ Release references to obtained interfaces after they are no longer
needed for proper resource clean-up!
+ For every reference count increment, ensure there is an equivalent
number of decrements.
BTW: Here's some COM coding conventions my team and I developed for the
Universal 3D Sample Software project that also apply for proper usage when
using the DirectFB API:
+ When passing an interface pointer to a function, the caller must not
release the interface pointer until the called function returns. This
needs to be specifically adhered to when multithreading or reentrancy
is involved.
+ When a copy of an interface pointer is made that will exist in a wider
scope than the original pointer, the interface's AddRef function must
be called. When the copy is no longer necessary, the interface's Release
function must be called. For example, if a function
"Register( IDirectFBSurface* pSurface )" of a component CSurfaceAnimation
takes as an argument a pointer to the interface IDirectFBSurface and in
the Register function implementation, it copies that pointer into the
CSurfaceAnimation data member m_pSurface, the AddRef function for the
IDirectFBSurface interface must be called. Immediately before destroying
the instance of CSurfaceAnimation, m_pSurface should have its Release
function called (provided it is non-NULL).
+ When a client is finished using a component or interface that it has
ownership of, the client must call the interface's Release function.
Note: A client will have ownership of an interface if it ever called a
function to receive an interface pointer to a component or it called the
AddRef function on the interface (and hopefully kept a pointer to it).
Best regards,
Timothy
--
Timothy Strelchun
CE Software Engineering
Digital Home Group
Intel Corporation
The views expressed above are my own and not those of Intel
_______________________________________________
directfb-users mailing list
directfb-users@directfb.org
http://mail.directfb.org/cgi-bin/mailman/listinfo/directfb-users
