HnxGC Programming API
| Name | Type | Description |
|---|---|---|
| HNXGC_CONFIG_NODLL | Preprocessor Definition | Use static linkage instead of default DLL linkage in some platforms, such as Win32. |
| HNXGC_CONFIG_NOSHORTHAND | Preprocessor Definition | defining this macro will disable short synonyms, such as lp<> for CLockedPtr<>, gcnew for HNXGC_NEW. |
| nullptr | symbol | Represents NULL pointer to make C++ source code compatible with CLR nullptr keyword.
pObj = nullptr;
|
| gcnew | Macro | Synonym of HNXGC_NEW. Can be undefined when need to use .NET CLR keyword "gcnew".
lp<CFoo> ptr = gcnew CFoo;
ptr = gcnew CFoo("John");
ptr = gcnew CFoo[10];
|
| HNXGC_NEW | Macro | Create a HnxGC managed object or an array of such objects.
lp<CFoo> ptr = HNXGC_NEW CFoo;
ptr = HNXGC_NEW CFoo("John");
ptr = HNXGC_NEW CFoo[10];
|
| gcnew_native | Macro | Synonym of HNXGC_NEW_NATIVE.
lp<int> ptr = gcnew_native(int);
ptr = gcnew_native(int)[100];
|
| HNXGC_NEW_NATIVE | Macro | Create a HnxGC managed object or an array of such objects.
lp<int> ptr = HNXGC_NEW_NATIVE(int);
ptr = HNXGC_NEW_NATIVE(int)[100];
|
| HNXGC_ENABLE | Macro | Define an empty Traverse routine for class that does not have any member pointer.
class CFoo {
int i;
HNXGC_ENABLE(CFoo)
};
|
| HNXGC_TRAVERSE | Macro | Define a Traverse routine in the declaration of user-defined class.
class CFoo {
mp<CFoo> m_pNext;
HNXGC_TRAVERSE(CFoo) {
...
}
};
|
| HNXGC_TRAVERSE_PTR | Macro | Report to system one or more HnxGC objects that are referenced by 'this' object. (can report maximum 16 objects in one HNXGC_TRAVERSE_PTR statement.)
HNXGC_TRAVERSE(CFoo) {
HNXGC_TRAVERSE_PTR(m_pNext, m_pPrev);
HNXGC_TRAVERSE_PTR(m_pParent);
}
|
| HNXGC_TRAVERSE_MULTIPLE_BEGIN HNXGC_TRAVERSE_MULTIPLE_END |
Macro | Report to system one or more HnxGC objects that are referenced by 'this' object. (no limitation on the number of objects being reported.)
HNXGC_TRAVERSE(CFoo) {
HNXGC_TRAVERSE_MULTIPLE_BEGIN {
m_pNext, m_pPrev,
m_pParent
}HNXGC_TRAVERSE_MULTIPLE_END
}
|
| HNXGC_TRAVERSE_CHAIN | Macro | Call other object's TRAVERSE routine to report their objects to system as 'this' one.
class CFoo : public CBar {
CBar m_oBar;
HNXGC_TRAVERSE(CFoo) {
HNXGC_TRAVERSE_CHAIN((CBar*)this);
HNXGC_TRAVERSE_CHAIN(&m_oBar);
}
};
|
| HNXGC_ONRECLAIM | Macro | Define a OnReclaim routine that will be called by HnxGC when the system detects the object is
unreachable. Application program normally declares dependence requirement in the OnReclaim routine.
class CFoo {
mp<CFoo> m_pNext;
HNXGC_TRAVERSE(CFoo) { ... }
HNXGC_ONRECLAIM() {
...
}
};
|
| HNXGC_DEPEND_DECLARE | Macro | Declare one or more dependence requirements. The 'depender' is by default the 'this' object, and
multiple, a maximum number of 16, objects are declared as 'dependee', which will not be collected prior
to the 'depender' object.
HNXGC_ONRECLAIM() {
HNXGC_DEPEND_DECLARE(m_pParent);
}
|
| HNXGC_DEPEND_MULTIPLE_BEGIN HNXGC_DEPEND_MULTIPLE_END |
Macro | Declare one or more dependence requirements. (no limitation on the number of objects being depended)
HNXGC_ONRECLAIM() {
HNXGC_DEPEND_MULTIPLE_BEGIN {
m_pNext, m_pPrev,
m_pParent
}HNXGC_DEPEND_MULTIPLE_END
}
|
| HNXGC_RESURRECT | Macro | Initiate a resurrection in OnReclaim routine.
HNXGC_ONRECLAIM() {
HNXGC_RESURRECT();
}
|
| HNXGC_COLLECT | Macro | perform a tracing garbage collection to collect circular referenced garbage.
HNXGC_COLLECT();
|
| HNXGC_DELETE | Macro | mandatory delete a HnxGC managed object.
lp<CFoo> ptr = gcnew CFoo;
HNXGC_DELETE(ptr);
|
| wp | C++ Class | Synonym of CWeakPtr. |
| CWeakPtr | C++ Class | A pointer to HnxGC managed object, but does not contribute to the liveness of the object it points to. |
| mp | C++ Class | Synonym of CMemberPtr. |
| CMemberPtr | C++ Class | A pointer as member variable of a HnxGC managed class. |
| lp | C++ Class | Synonym of CLockedPtr. |
| CLockedPtr | C++ Class | A pointer that will cause the referent HnxGC object locked, and prevent the object and its descendants from being collected. It should not be used as member variable of a HnxGC managed class. The typical places it is used include (1) execution stack, (2) static storage area. The assignment between 2 CLockedPtr is "move" semantics. |
| duplicate | Method of CLockedPtr | Return a duplicated CLockedPtr<> of the 'this' pointer.CLockedPtr CLockedPtr::duplicate(); lp<CFoo> p1 = gcnew CFoo; lp<CFoo> p2 = p1.duplicate(); |
| attach | Method of CLockedPtr | clear original reference and assume the new reference without introducing "lock" operation on the new referenced object.CWeakPtr CLockedPtr::attach(void *p); lp<CFoo> p1 = gcnew CFoo; void *p = p1.detach(); lp<CFoo> p2; p2.attach(p); |
| detach | Method of CLockedPtr | return original reference and reset the pointer.void * CLockedPtr::detach(); lp<CFoo> p1 = gcnew CFoo; void *p = p1.detach(); lp<CFoo> p2; p2.attach(p); |
| InteriorPointer | Inline Function | create an interior pointer from 2 addresses, the beginning of the outer object and the interior data address.
CLockedPtr<T> InteriorPointer(T *pData, <HnxGC Pointer> pObj); lp<CFoo> pObj = gcnew CFoo; lp<int> p = InteriorPointer(&pObj->i, pObj); pObj = nullptr; *p = 100; |
| interior_cast | Inline Function | cast an outer object address to its base object.
CLockedPtr<T> interior_cast(<HnxGC pointers>); lp<CDerived> pObj = gcnew CDerived; lp<CBase> p = interior_cast<CBase>(pObj); pObj = nullptr; |
HnxGC Library Binary Interface
| Name | Type | Description |
|---|---|---|
| _hnxgc_operator_new | "C" function call | Create a HnxGC managed object or an array of such objects according to specified class info interface.void * _hnxgc_operator_new( void * pRuntimeClassInfo, size_t objSize, size_t totalSize, size_t nFlags); |
| _hnxgc_assign_lptr | "C" function call | Assign a HnxGC managed object reference to a CLockedPtr style pointervoid * _hnxgc_assign_lptr(void *dest, void *src); |
| _hnxgc_assign_mptr | "C" function call | Assign a HnxGC managed object reference to a CMemberPtr style pointervoid * _hnxgc_assign_mptr(void *dest, void *src); |
| _hnxgc_garbage_collect | "C" function call | Perform tracing garbage collection and other swissknife functionsint _hnxgc_garbage_collect(void * pType = 0); |
| _hnxgc_traverse_report | "C" function call | Report one or more HnxGC object(s) that are referenced by 'this' HnxGC object to the HnxGC system.
Be used in Traverse callback routine.void _hnxgc_traverse_report( void *caller, size_t n, void **ppObj); |
| _hnxgc_onreclaim_change_depender | "C" function call | Change the current depender object in OnReclaim callback routine.void * _hnxgc_onreclaim_change_depender( void *caller, void *pDepender); |
| _hnxgc_onreclaim_declare | "C" function call | Declare a dependence requirement in OnReclaim callback routine.void _hnxgc_onreclaim_declare( void *caller, size_t n, void **ppObj); |
| _hnxgc_onreclaim_resurrect | "C" function call | Initiate a resurrection in OnReclaim callback routine.void _hnxgc_onreclaim_resurrect(void *caller); |
| _hnxgc_destruct_object | "C" function call | Mandatory destruct a live HnxGC object.int _hnxgc_destruct_object(void *pObj); |
| _hnxgc_lock_object | Pseudo API (inline function) | Lock a HnxGC object to prevent it from reclamation.void * _hnxgc_lock_object(void * pObj); |
| _hnxgc_unlock_object | Pseudo API (inline function) | Unlock a locked HnxGC object to allow it to be collected.void * _hnxgc_unlock_object(void * pObj); |
| _hnxgc_addref_object | Pseudo API (inline function)) | Add a reference to a HnxGC object.void * _hnxgc_addref_object(void * pObj); |
| _hnxgc_release_object | Pseudo API (inline function) | Release a reference to a HnxGC object.void * _hnxgc_release_object(void * pObj); |