This document describes the user API for configuring RTSJ support in RTI Connext.

This document contains:

Please do not hesitate to contact RTI with questions or comments about this release. We welcome any input on how to improve RTI Connext to suit your needs.

Acronyms and Definitions

JAR - Java Archive. A file format used for packaging Java libraries.
JVM - Java Virtual Machine. The application that executes Java byte code, including RTI Connext and the user application that uses it.
RTSJ - Real Time Specification for Java. A set of specification for additions to the Java platform to enable Java programs to be used for real-time applications. See http://www.rtsj.org/specjavadoc/book_index.html for the pertinent API documentation.
RT - Real-time Thread. A type of thread supported by RTSJ-compliant Java virtual machines that offers limited real-time scheduling.
NHRT - No Heap Real-time Thread. A type of thread supported by RTSJ-compliant Java virtual machines that offers real-time scheduling but does not allow access to objects stored on the managed heap.

Overview

The RTSJ configuration API described in this documentation exists in the com.rti.ndds.rtsj package and is provided separately from RTI Connext. Users of this API will receive a second installation package from RTI to be used in addition to the libraries accompanying their standard RTI Connext installation.

The entrypoint into the RTSJ support of RTI Connext is the com.rti.ndds.rtsj.RtsjThreadSupport class. The documentation for this and other types may be found under "Class List" in the tree view at left.

Compatibility

The behavior of RTI Connext with respect to RTSJ is described in the following table.

	JVM with RTSJ support	JVM without RTSJ support
RTI Connext with RTSJ support	RTSJ-specific RTI Connext features are available as described in this documentation.	RTI Connext-related code will still compile, assuming it does not use any RTSJ-specific types directly. Usage of the RTI RTSJ APIs described in this documentation is safe, provided that you do not specify the use of RTSJ-specific threads or memory areas. Other usages are not; in particular, a call to com.rti.ndds.rtsj.RtsjThreadSupport.register() passing properties specifying RTSJ-specific threads or memory areas will result in a runtime exception.
RTI Connext without RTSJ support	RTI Connext operates normally, although the RTSJ-specific API described in this documentation will not be available. Note that this limitation does not preclude the use of RTSJ-specific code elsewhere in your application.	RTI Connext operates normally; the RTSJ-specific API described in this documentation will not be available. This is the normal mode of use for customers who are not using RTSJ.

Programming API

In an RTSJ JVM, there are three different types of threads: regular, real-time (RT), and no heap real-time (NHRT) threads. They are encapsulated in the com.rti.ndds.rtsj.ThreadKind class.

There are four different types of memory areas: regular heap, immortal, LT scoped, VT scoped memory areas.

The thread and memory area properties of the internal RTI Connext threads (receive, event, database, and asynchronous publishing) may be customized using instances of the com.rti.ndds.rtsj.RtsjThreadProperty_t class. These instances combine together into the com.rti.ndds.rtsj.RtsjProperty_t class, which defines how internal threads behave in a given RTI Connext application.

The com.rti.ndds.rtsj.RtsjThreadSupport class provides a registration interface that sets the properties associated with the domain participant factory. In case an attempt is made to register RTSJ threads on a non-RTSJ-compatible JVM, this method will throw a com.rti.dds.infrastructure.RETCODE_INCONSISTENT_QOS exception.

Detailed descriptions and definitions of the above classes can be found in the left browser frame.

Threads, Memory Areas, and RTI Connext

Before you will be able to use RTI Connext effectively with RTSJ, you will have to understand the different threads that are created and used by the middleware and the interactions between them. General, non-RTSJ-specific information on this topic may be found in your RTI Connext User's Manual.

This RTSJ configuration API allows you to customize the memory areas used by each RTI Connext thread. When so doing, it is important to know which operations may be called, and which objects referred to, in which threads. The following is a set of guidelines.

Entity Creation: RTI Connext threads are spawned from the thread that creates the entity that manages them (the publisher in the case of asynchronous publishing threads, the domain participant in the case of all others). The Java Thread (or a subclass) object itself is allocated in the memory area indicated in the corresponding RtsjThreadProperty_t object. Therefore, in order to create the thread, it must be possible to enter the indicated memory area from the thread that is creating the entity.
Entity Destruction: Because of the way that RTI Connext manages entity lifecycles (see the section in the User's Manual about the database thread), some entity finalization will occur in the thread that explicitly calls the corresponding delete_* method, and some finalization will occur in the database thread. Therefore, both of these threads must be able to refer to the memory area in which the entity was originally created.
Listener Callbacks: The com.rti.dds.subscription.DataReaderListener.on_data_available and com.rti.dds.subscription.SubscriberListener.on_data_on_readers callbacks are called in the context of a receive thread. All other callbacks are called in the context of the event thread.

Available Documentation

Documentation for RTI RTSJ Compatibility Kit is provided in two forms: the HTML API reference and PDF documents.

The PDF documents are:

RTI RTSJ Extension Kit Installation Guide. Download and installation instructions

RTI RTSJ Extension Kit Release Notes. known issues.

RTSJ API Reference Manual. PDF version of the HTML documentation for the RTSJ Extension Kit API.

HTML API reference:

The HTML API documentation can be accessed through the tree view in the left frame of the web browser window.