WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

NetKernel runs within the Java virtual machine and although many aspects of ROC are abstracted from the underlying platform. Java's memory management is one thing that NetKernel cannot take control of. A consequence of this is that it is possible for 3rd party libraries to cause memory leaks that can eventually cause NetKernel to fail with out-of-memory errors.

It is important to distinguish between leaks and normal high heap usage. Although the core of NetKernel is highly optimised to minimise heap usage, large datasets and some complex libraries may have high memory requirements. You will need to ensure adequate heap to deal with all eventualities. Careful system design with consideration for limiting maximum concurrency with endpoints like the throttle will help.

All of the standard modules supplied by 1060 including main and universe sets are thoroughly tested for leaks and unless explicitly stated as experimental or not production ready, they are known to be leak free.

If you are developing your own libraries that integrate 3rd party or even your own code libraries it is important to properly test to ensure they do not leak. Leaks may occur because of intrinsic limitations of the library or because of errors in the integration into endpoints or representations you may develop.

Leaks usually come about in one of several ways:

  • A leak every time an endpoint is invoked. This is usually the easiest to spot and simple thrash testing can uncover a monotonically rising heap.
  • A leak every time a custom representation is disposed-of, especially if the representation holds onto live state within a library. This may happen due to a failure to clean up properly (See Representation Lifecycle)
  • A leak every time the module is recommissioned. Often you will see this during development especially if you are using the dynamic tag - do not ignore out-of-memory errors. See Endpoint Lifecycle to see where you can place hooks to clean up properly when an endpoint is decommissioned.

Several tools can be used to help you keep an eye on heap usage:

  • Status Tab - the status tab on the backend fulcrum contains a live graph of historical heap usage alongside cache, requests and CPU usage. If you see the heap rising steadily and the cache size being squeezed downwards that is a good indication of a leak.
  • JConsole - this JDK tool can be used for external monitoring of a Java virtual machine. It will give heap usage graph similar to the status tab.
  • JMap/JProbe - If you have identified that you have a leak these two tools can help you track it down. JMap comes as part of the JDK and can be used to capture a full heap dump from any JVM. It is particularly useful for production servers because it doesn't require restarting or specially configured setup. You will however need a separate analysis tool. Eclipse has a good heap analyser. JProbe is a powerful to for analysing heap usage but is only really suitable at development time because of the large overhead on performance it has.

Simple Heap Dump Tool

Running the following Groovy script in the scripting playpen will allow you to perform a heap dump from within a running NetKernel instance. (Note this is known to work on a Sun JVM)...

//Really Simple Heap Dumper
import com.sun.management.HotSpotDiagnosticMXBean
import java.lang.management.ManagementFactory
import javax.management.MBeanServer

dumpfile="heap.bin"

server = ManagementFactory.getPlatformMBeanServer()
hotspotMBean = ManagementFactory.newPlatformMXBeanProxy(
    server,
    "com.sun.management:type=HotSpotDiagnostic",
    HotSpotDiagnosticMXBean.class
);
hotspotMBean.dumpHeap(dumpfile, true)
context.createResponseFrom("Heap Dumped to $dumpfile")

It is generally a good idea to clear the representation cache before attempting to dump the heap to eliminate the noise of the transient state of cached representations.