Remarks

This method receives an object and clears all its objects references by storing the .Null. value on all properties pointing to another object.

This method must be used prior to release or free a pointer to an object with mutual references with other objects.

Mutual references are established when a relationship between 2 objects is mutual, it is, both ends of the relationship reference each other.

When a single reference relationship in a persistent class is marked as mutual (see the Schema Manager mapping tool) like the Wife/Husband property pair on Person class in the example shown below, the Session.SyncObject method can be used to refresh/force the mutual relationship  by storing objects references on both ends (referencing both objects each other).

Note this may lead to circular references avoiding objects to release or destroy properly.

To help work with mutual references, the Session.ClearObject method is used to clear all references from an object prior to release or clear the object pointer.

oJohn=CREATEOBJECT("husband")

oJohn.FirstName="John"

oMary=CREATEOBJECT("wife")

oMary.FirstName="Mary"

oMary.Husband=oJohn

oSession.SyncObject(oMary)

? oJohn.Wife.Name    --> "Mary"

? oMary.Husband.Name --> "John"

? oMary.Husband.Wife.Name --> "Mary"

oSession.ClearObject(oMary)

oMary=.Null.

oJohn=.Null.

*------------------------------

DEFINE CLASS person AS CUSTOM

   FirstName = ""

   LastName  = ""

   BirthDay  = {}

ENDDEFINE

DEFINE CLASS husband AS person

   Wife = .NULL.

ENDEFINE

DEFINE CLASS wife AS person

   Husband = .NULL.

ENDEFINE

In the sample, oJohn and oMary objects are created, then oMary.Husband property is set to point to the oJohn husband instance.

Then, the oSession.SyncObject method is called. It stores a pointer to the oMary instance into the oJohn.Wife property, using the information stored on the mapping schema.

Both objects reference each other now.

While mutual references are powerful, they must be carefully handled because, as you may observe in the sample, there is a circular reference now between both objects, and it may lead to a deadlock or memory leak.

If both objects pointers (oJohn and oMary) where cleared or simply get out of scope, none of the instances will be released from memory because there is still a reference on each object pointing to the other. Neither the destroy event on those objects will fire.

The Session.ClearObject method is used to clear all references from an object instance, prior to free the object pointer, ensuring all instances will be removed from memory safely.

See Also

Session.SyncObject method