When any context API has a return result that is a Rexx object instance, the source API context will protect that object instance from garbage collection for as long as the source API context is valid. Once the API context is destroyed, the accessed objects might become eligible for garbage collection and be reclaimed by the interpreter runtime. These object references are only valid until the current context is destroyed. They cannot be stored in native code control blocks and be used in other thread contexts. If you wish to store object references so that they can be accessed by other thread contexts, you can create a globally valid object reference using the RequestGlobalReference() API. A global reference will create a global on an object that will protect the object from the garbage collector until the interpreter instance is terminated. Protecting the object will also protect any objects referenced by the protected object. For example, using RequestGlobalReference() to protect a Directory object will also protect all of the directory keys and values. The global reference can be used with any API context valid for the same interpreter instance. Once you are finished with a locked object, ReleaseGlobalReference() cac remove the object lock and make the object eligible for garbage collection.
On the flip side of this, sometimes it is desirable to remove the local API context protection from an object. For example, if you use the ArrayAt() API to iterate through all of the elements of an Array, each object ArrayAt() returns will be added to the API context's protection table. There is a small overhead associated with each protected reference, so iterating through a large array would accumulate that overhead for each array element. Using ReleaseLocalReference() on an object reference you no longer require will remove the local lock, and thus limit the overhead.