Learn more about MATLAB Builder JA

Managing Native Resources

On this page…
What Are Native Resources? Using Garbage Collection Provided by the JVM Using the dispose Method Overriding the Object.Finalize Method

What Are Native Resources?

When your code accesses Java classes created by the MATLAB Builder JA product, your program uses native resources, which exist outside the control of the Java Virtual Machine (JVM).

Specifically, each MWArray data conversion class is a wrapper class that encapsulates a MATLAB mxArray. The encapsulated MATLAB array allocates resources from the native memory heap.

Note   Native arrays should always be explicitly freed. Because the Java wrapper is small and the mxArray is relatively large, the JVM memory manager may not call the garbage collector before the native memory becomes exhausted or badly fragmented.

Back to Top

Using Garbage Collection Provided by the JVM

When you create a new instance of a Java class, the JVM allocates and initializes the new object. When this object goes out of scope, or becomes otherwise unreachable, it becomes eligible for garbage collection by the JVM. The memory allocated by the object is eventually freed when the garbage collector is run.

When you instantiate MWArray classes, the encapsulated MATLAB also allocates space for native resources, but these resources are not visible to the JVM and are not eligible for garbage collection by the JVM. These resources are not released by the class finalizer until the JVM determines that it is appropriate to run the garbage collector.

The resources allocated by MWArray objects can be quite large and can quickly exhaust your available memory. To avoid exhausting the native memory heap, MWArray objects should be explicitly freed as soon as possible by the application that creates them.

Back to Top

Using the dispose Method

The best technique for freeing resources for classes created by the MATLAB Builder JA product is to call the dispose method explicitly. Any Java object, including an MWArray object, has a dispose method.

The MWArray classes also have a finalize method, called a finalizer, that calls dispose. Although you can think of the MWArray finalizer as a kind of safety net for the cases when you do not call dispose explicitly, keep in mind that you cannot determine exactly when the JVM calls the finalizer, and the JVM might not discover memory that should be freed.

Code Fragment: Using dispose

The following example allocates an approximate 8 MB native array. To the JVM, the size of the wrapped object is just a few bytes (the size of an MWNumericArray instance) and thus not of significant size to trigger the garbage collector. This example shows why it is good practice to free the MWArray explicitly.

/* Allocate a huge array */
int[] dims = {1000, 1000};
MWNumericArray a = MWNumericArray.newInstance(dims,
   MWClassID.DOUBLE, MWComplexity.REAL);
        .
        .  (use the array)
        .

/* Dispose of native resources */
a.dispose();

/* Make it eligible for garbage collection */
a = null;

The statement a.dispose() frees the memory allocated by both the managed wrapper and the native MATLAB array.

The MWArray class provides two disposal methods: dispose and disposeArray. The disposeArray method is more general in that it disposes of either a single MWArray or an array of arrays of type MWArray.

Code Fragment: Using try-finally to Ensure Resources Are Freed

Typically, the best way to call the dispose method is from a finally clause in a try-finally block. This technique ensures that all native resources are freed before exiting the method, even if an exception is thrown at some point before the cleanup code.

Code Fragment: Using dispose in a finally Clause.  

This example shows the use of dispose in a finally clause:

/* Allocate a huge array */ 
MWNumericArray a; 
try 
{ 
   int[] dims = {1000, 1000}; 
   a = MWNumericArray.newInstance(dims, 
      MWClassID.DOUBLE, MWComplexity.REAL); 
   . 
   . (use the array) 
   . 
} 

/* Dispose of native resources */ 
finally 
{ 
   a.dispose(); 
   /* Make it eligible for garbage collection */ 
   a = null; 
} 

Back to Top

Overriding the Object.Finalize Method

You can also override the Object.Finalize method to help clean up native resources just before garbage collection of the managed object. Refer to your Java language reference documentation for detailed information on how to override this method.

Back to Top

Handling Errors

Improving Data Access Using the MCR User Data Interface and MATLAB Builder JA

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS