Utilities: Recycling

Other than on the PC with its constantly enlarging sizes of RAM, Memory is precious on small devices like the RCX.
Since there is no mechanism on Java to free memory at a determined point of time, and particularly with the lack of a garbage collector with leJOS, allocating objects on the heap is liable to set forth some kind of "out of memory" behavior of your robot. In peculiar, memory consuming collections like arrays are prone to make itself a nuisance.

To help this, some new josx.util package located classes have been introduced in leJOS' version 2.1.0 with the task of providing a recycling mechanism:

Recyclable an interface for an recyclable object
AbstractRecycable an abstract base class for Recyclables which implements some of Recyclable methods
RecyclableArray a recyclable array implementing the Recyclable interface
Recycler an abstract base class which is able to recycle Recyclables
ArrayRecycler an array recycler

The idea is simple but effective: instead of creating every new instance of your object with its constructor using new(), you order such a new instance by a Recycler, which may be thought as a factory that stores currently unused objects and delivers them on order.
All the user has to do is

to implement the Recyclable interface for the classes he wants to be recycled that way,
to order such objects from the recycler by calling Recycler.allocate(),
to hand them out back to the recycler when they are no longer needed (by calling Recycler.recycle([recyclable object])) and


		to extend the abstract Recycler class in overwriting its createInstance()
		method (don't worry: as a rule that requires no more than creating a new instance of your recyclable class using 
            	new).



        
        Declaring instances of a class to be recycable
        For the instances of a class to be recycable, the class should extend the abstract 
        josx.util.AbstractRecyclable class; this means, it has to implement the following two 
        methods:
        
            public void init() called, when an instance is allocated by the recycler
            public void release() called by the user when the instance is no longer needed; you should 
                release any resources here, including nested Recyclables.
        

        Of course you are free to implement the Recyclable directly; in this case you
        have to implement also the getNextRecyclable() and setNextRecyclable() by
        yourself.
        

        
        Building a Recycler
        To recycle recyclable instances, you need a recycler which manages the process of allocating and releasing
        the memory for these instances. This is most easily done by extending the abstract 
        josx.util.Recycler class, which means that your recycler has to to implement the 
        
            public Recyclable createInstance()
        
        method and adapt it to create an instance of your particular recyclable class.
        

        Of course you can build your own recycler, which means that you have to take care
        of the complete recycling process by yourself.
        

        
        
Recycling array entries
        For recycable arrays there exists the josx.util.RecyclableArray class already,
        which delivers all the basic functionalities you would expect from an array like get(), put() and
        getLength().
        

        The associated recycler is josx.util.ArrayRecycler which 
        extends josx.util.Recycler and implements its abstract methods
        - ready to be used.
 
        
        Two complete examples that use the Recycling classes
        are ObjectRecyclingSample.java and ArrayRecyclingSample.java 
        which may be found in the examples/test/recycling 
        section of the leJOS tree.

        
        The Recycling API
        may be found here.


        
        
        The leJOS Tutorial
        

        
            
                
                    
                    
                    

                
                    
                    Start of Tutorial
                    >
                    Start of Trail