RTSJ Code Idioms

Encapsulated Methods

Encapsulate a Method by implementing it as a private class that implements Runnable That private class has a run method that must be implemented You instantiate an instance of the private class within the containing class (the class the method is supposed to belong to)

This gives may options for memory management

You then enter a memory passing the instance of the private class

Operation

When creating the private class you can chose where objects within the scope of the run method are created

Parent scope or run scope

Objects created within the parent scope are visible to both the parent and the run scope

Enabling the passing of parameters and results between the two

Singleton operation prevents memory leaks at the parent scope

Wedge

A Wedge is an object that encapsulates

A RealTimeThread called a WedgeThread An AsyncEventHandler called a WedgeKillHandler An AsyncEvent called a WedgeKillEvent A WaitFreeWriteQueue to communicate between the WedgeKillHandler and the WedgeThread

Operation

A ScopedMemory is created A Runnable enters that ScopedMemory and creates a Wedge

The creation of the Wedge instantiates and interconnects the Wedge sub-components

Places a reference to the wedge in the ScopedMemory's Portal

The WedgeThread blocks trying to read the WaitFreeWriteQueue When you want the ScopedMemory to reclaim any contained objects, you have a Runnable enter the ScopedMemory, pick up the Wedge from the Portal and fire the WedgeKillEvent

This allows the WedgeThread to complete and terminate the Execution Context that was pinning the contents of the ScopedMemory

Initializers and Finalizers

Code Idiom for Managing Scoped Memories

Generally need two levels of initialization and finalization

One for the Scoped Memory itself One for the Objects that exist within the scoped memory

Scoped Memory

Initializer

Contains a Runnable that is used to enter the Scoped Memory and create the Wedge to pin it open Contains a Runnable that is used to enter the Scoped Memory and fire the AsyncEvent to shutdown the Wedge

Finalizer

Objects in the Scoped Memory

Initializer

Contains a Runnable that is used to enter the Scoped Memory and create Objects (Data Objects, Threads, Handlers, ) Usually starts any threads that are created May or may not wait for those threads to finish Used to clean up any Data Objects

Finalizer

Not usually necessary as the cease to exist on reclaimation Must happen or this defeats the Wedge Idiom

Needs to shutdown or stop any free running Threads

Basic Operation

Create the Scoped Memory

Enter it running the ScopedMemoryInitializer to install the Wedge

This initializer returns from the scope

Enter it running the Object or Mode Initializer to create and necessary Objects and Threads

This initializer may or may not return from the scope

When Finished

Enter the scope running the Object or Mode finializer

This finalizer will kill the Wedge When this Runnable returns from the scope the Objects will be reclaimed The Scoped Memory will still exist, it will just be empty

Temp Scopes

A ScopedMemory that contains temporary Objects Used when you need to have a non GCd Memory Area

So it is not bothered by GC Delays

The purpose is to be able to freely create and use Objects while an Execution Context is running, and then be able to destroy all of those Objects in a single operation This allows for a repetitive use of a ScopedMemory and minimizes temporary object destruction

Two Versions

Version 1 simply arranges to reuse a single ScopedMemory

Applicable when the Temp Scope ca be created once and is only used by a single Runnable

Version 2 uses 2 ScopedMemories, a small BridgeScope and a dynamically created Temp Scope

Applicable when you may need to use varying size Temp Scopes, or when you need to select different functionalities with different needs based on the Runnable

Version 1

Create an Object in the parent Scope that has a reference to another ScopedMemory the Temp Scope Create an Encapsulated Method in that Object and instantiate an instance of that Encapsulated Method

Create the Encapsulated Method instance in the parent scope

Copy input parameters into the Encapsulated Method Fields

These Fields exist in the parent scope

Invoke the Encapsulated Method by entering the Temp Scope In the run method of the Encapsulated Method make sure return values are copied into the Fields of the Encapsulated Method

Which are still in the parent scope

Return from the Temp Scope

Objects created while in the Temp Scope are destroyed in bulk emptying it Return values were populated in Objects in the parent scope

Version 2

Create an Object in the parent Scope that has a reference to another ScopedMemory the BridgeScope Create an Encapsulated Method in that Object and instantiate an instance of that Encapsulated Method - call it the Original Encapsulated Method (OEM) Copy input parameters into the OEM Fields Invoke the OEM by entering the BridgeScope The run method of the OEM can use values passed in to select and dynamically create (in the BridgeScope) another New Encapsulated Method (NEM) and another Temp Scope

These objects now exist in the BridgeScope

The NEM is now invoked by entering the Temp Scope

The return values must be copied to the NEM Fields (which exists in the BridgeScope) The NEM returns cleaning the Temp Scope

Execution resumes in the OEM copying the NEM return values to the OEM (which still exists in the parent scope

The OEM returns cleaning the BridgeScope (and deleting the NEM and Temp Scope)