AUTOGCN parameter

Garbage collection threshold

Summary

Default value

0

Parameter type

User

Where set

User resettable

Related products

Janus SOAP

Introduced

Sirius Mods 7.5

Description

SOUL performs garbage collection automatically at user logout: that is, at logout it removes user-created objects that were not discarded by the user or by SOUL during and after each request. This garbage collection process can also be invoked explicitly (by %(object):GarbageCollect), and it may be time consuming. The AUTOGCN User parameter lets you invoke garbage collection automatically during a user session whenever normal post-request cleanup “leaves behind” a number of objects that meets or exceeds the AUTOGCN value.

At the end of a request, normal SOUL object cleanup discards all objects — if there are no global or session objects defined in the request. However, if the request created global or session objects, normal cleanup discards only objects that are not global and not session and have no references by other request object variables. Global and session objects and any other objects they reference or that are still referenced by other request object variables are not discarded.

Garbage collection sorts through these non-discarded objects and removes those that are not global or session objects or are not accessible, directly or indirectly, from a global or session object. An orphan cycle is a prime example of such an unreachable object. Orphans reference each other and may be complex, associated with many resources. By invoking garbage collection automatically, the AUTOGCN parameter lets you keep the number of non-discarded, referenced but unreachable, objects below a threshold value.

If AUTOGCN is greater than 0, garbage collection runs whenever the number of referenced, non-global, non-session objects created by the current request and not discarded after the current request's normal cleanup is at least the AUTOGCN threshold number.

If AUTOGCN is 0, automatic garbage collection is not invoked until user logout.

If garbage collection runs, whether AUTOGCN-invoked or via a GarbageCollect method call, you can be notified with a message if you set the GCSTATS User parameter to one of its non-default values. GCSTATS parameter produces a message that indicates the number of objects the garbage collection discarded and how long it took to do so.

The request in the following example creates 50 self-referential, orphan objects which are not discarded by normal request cleanup because the request also creates a global object. The request does not trigger automatic garbage collection, however, because the AUTOGCN threshold is 70.

R GCSTATS X'03' R AUTOGCN 70 Begin class Linked public variable next is object Linked end public end class %cycle is object Linked %gl is object linked global %i is float %gl = new for %i from 1 to 50 %cycle = new %cycle:next = %cycle end for print 'End of request' End

If the request runs a second time, the result is the same as the first time, and now one hundred orphans remain in storage. If the request runs a third time but AUTOGCN is set to 30, the 50 orphans that are newly created and not discarded exceed the AUTOGCN threshold, and automatic collection runs, discarding the orphans from all three requests, but not discarding the global object. The third request produces the following result:

End of request *** MSIR.0995: (implicit) Garbage collection completed in 0ms realtime with 0ms CPU time. Discarded 150/151 objects.

Note: If the second and third times the request ran it was modified to exclude the creation of the global object, the requests' orphans would still not be discarded, because the presence of the global object in the initial request affects object cleanup for the life of the user thread, as long as the global is not explicitly discarded.

For more information about garbage collection, see Cleanup by garbage collection.