View on GitHub

Chapter 11
The Runtime Environment

11.1 Overview

The REDHAWK runtime environment provides a mechanism for managing the life cycle (creation/teardown/initialization) of Components as well as the interconnection of deployed Components.

The primary goal of the runtime environment is to support the necessary infrastructure to deploy and manage interconnected Components as a running Application.

The runtime environment is personified by two binaries, a Domain Manager program and a Device Manager program. The Domain Manager program hosts an instance of a DomainManager class as well as supporting objects (Application Factory, Application, File Manager). The Device Manager program hosts an instance of a DeviceManager object and an instance of a File System. The only reason why the major classes making up these programs are imported is because their API is remotely available, so a user can arbitrarily interact with these objects. Irrespective of their API, these objects exclusively reside in either the Domain Manager or Device Manager programs.

A single REDHAWK system instance has one Domain Manager and an arbitrary number of Device Managers. The Domain Manager’s role is as a central bookkeeper as well as a single point where Applications can be deployed or torn down. A Device Manager is present in each host in the REDHAWK network area; in a purely processing context, there would be a single Device Manager in each computer that is intended to host running Components. Each Device Manager has associated with it a set of Devices that act as proxies for whatever hardware is running on the computer; in a purely processing context, there is a single Device proxy describing the microprocessor for each hardware platform Device Manager.

The Domain Manager program:

11.1.1 Launching a Domain

If REDHAWK was installed from RPMs, a Domain Manager and Device Manager are ready for immediate use on the localhost. To launch a default Domain in the IDE, follow these steps:

  1. In the REDHAWK Explorer View (by default, on the right-side of the window) right-click the Target SDR element and select Launch Domain(Figure 11.1).


    PIC
    Figure 11.1: Launching a Domain


  2. In the Device Manager section of the Launch Domain Manager window, select DevMgr_hostname (Figure 11.2).


    PIC
    Figure 11.2: Device Manager Selection


  3. Click OK.

This launches both a Domain Manager and a Device Manager that manages a single GPP Device. The output from both the Domain Manager and Device Manager is displayed in the Console view. If this view is not visible, select Window > Show View > Console. To stop these processes, click the Terminate icon (red square) (Figure 11.3). To toggle between consoles, click the Display Selected Console icon (computer monitor) (Figure 11.4).


PIC

Figure 11.3: Terminate Icon



PIC

Figure 11.4: Display Selected Console Icon


The REDHAWK_DEV Domain connection is displayed in the REDHAWK Explorer View (Figure 11.5). Its state is CONNECTED and there are no errors. A Domain Manager process and a Device Manager process now exist on the host.


PIC

Figure 11.5: Domain connections shown in IDE


11.1.2 Shutting Down the Domain

Normally, the Domain Manager and Device Manager remain running indefinitely; these programs are designed to remain running for extended periods of time as different parts of the overall Domain (e.g., Device Managers, Applications, and files on $SDRROOT) come and go. However, for the purpose of the following procedure, the process for shutting down a running Domain is explained. To cleanly shutdown, it is best to disconnect the Domain and stop the processes that have been started.

  1. In the REDHAWK Explorer View, right-click the REDHAWK_DEV Domain and select Disconnect (Figure 11.6).
  2. In the Console view, select the Device Manager Console from the Display Selected Console icon (Figure 11.4).
  3. To stop the Device Manager, click the Terminate icon (Figure 11.3).
  4. In the Console view, select the Domain Manager Console from the Display Selected Console icon (Figure 11.4).
  5. To stop the Domain Manager, click the Terminate icon (Figure 11.3).
  6. Select File > Exit.


PIC

Figure 11.6: Disconnect From Domain


The Domain Manager and Device Manager processes no longer exist on the host. The Domain entry remains in the REDHAWK Explorer View with a DISCONNECTED state indicating that the Domain is no longer visible. This decoupling of the running Domain from the environment enables the REDHAWK Explorer to interact with an arbitrary number of Domains on a network where each Domain’s life cycle is outside the control of the IDE.

11.2 The Domain Manager

The Domain Manager interface is in charge of the control and configuration of the entire systems Domain.

Its primary responsibilities can be grouped into three main categories:

Each Domain has a single Domain Manager that keeps track of a File Manager, a set of Device Managers, and a set of Application Factories. The Domain Manger maintains information on all aspects of the Waveform’s implementations contained within its system.

The Domain Manager is configured from the DMD XML file that is located at $SDRROOT/dom/Domain. This file contains the Domain’s name, an ID and a description of the Domain.

11.2.1 Launching a Domain Manager from the command line

Enter the following commands to launch a Domain Manager from the command line:

11.2.2 Registration

The Domain Manager is able to maintain information about all working parts and interactions in the environment through registration. It can be thought of as the Domain Manager’s responsibility of bookkeeping for the system.

Any time a Device Manager, Device, Service or Application is created within the system, it is registered through the Domain Manager. Likewise, when they are destroyed, they are unregistered from the Domain Manager. These tasks are handled through a serious of register() and unregister() functions for each of the different modules that the Domain Manager is responsible for supporting.

11.2.3 Core Framework Administration

The Domain Manager has Core Framework administrative duties that are required to provide interface access to its registered items. The API of the Device Managers, Application Factories, Applications, and the File Manager that are registered in the Domain are made available to be accessed from an external piece of software.

This is made available so that changes can be made from outside of the running Domain. A Python module is distributed with REDHAWK that allows for simple interfacing with a running Domain. This allows for runtime inspection and tweaking of the environment. For more on this, refer to Chapter 12.

11.2.4 Human Computer Interfacing

The Domain Manager is also responsible for providing functionality that allows for simple interaction between the user and the system, granting the user control over the running Domain. Functionality exists that provide the ability to configure the Domain, get its current Device, Service and Application capabilities and launch maintenance functions.

Capabilities are managed through a series of data structure sequences. Lists are maintained for all Services, Device Managers and Devices that have been registered with the Domain. Each entry in the list contains name and identification information as well as a reference to the object that has been registered. For any Application that has been installed, a reference to its Application Factory is stored in a list along with its name and identification information. Once the Application has started, its reference, along with all relevant identification, Component, connection and ordering information is stored for later retrieval.

11.2.5 Persistence Store

A unique feature of the Domain Manager is the ability to recover from catastrophic failures through Domain Persistence. In order to make use of Persistence, a compile-time option must be specified. Ensure that the Core Framework has been compiled from source and that ./configure was ran with --enable-persistence=persist_type (Section D.1.2).

With this feature enabled, all bookkeeping data structures that are used to maintain information about Services, Devices, Device Managers, Applications and Application Factories are written to a database whenever any change is made to them. This database file needs to be specified upon launch of the Domain Manager with the --dburl <file path> argument:

Then, upon failure of the Domain Manager, all IDs and references to objects within it Domain are stored. Since these objects themselves are actually separate processes, the Domain Manager can be relaunched with the same arguments, and it is restored to the previous state. When the Domain Manager gets launched, it calls the restoreState() function with a file path string as an argument. It then opens the given database file and attempts to parse out any stored information in order to reconnect those processes with the Domain. Once this is finished, the Domain is rebuilt to the state it was in before it died.

11.3 File System

The File System interface defines CORBA operations that exists to provide a runtime abstraction of an OSs real file system. It gives REDHAWK the ability to have a single interface for reading and writing individual files within a file system regardless of the underlying implementation in the OS.

Files that are stored on the File System may be either plain files or directories.

Characters and symbols that are valid in directories and file names consist of:

Path names are structured according to the Portable Operating System Interface (POSIX) specification where the “/” (forward slash) is a valid character that acts as the separator between directories.

Additionally, the File System interface provides implementation of many standard functions such as:

File System attached to the Domain Manager mounts with $SDRROOT/dom as the root. Each Device Manager mounts a File System with $SDRROOT/dev as the root.

11.3.1 File Manager

The File Manager exists to manage multiple distributed file systems. This interface allows these file systems to act as a single entity, though they may span multiple physical file systems on different pieces of hardware. This provides for a distributed file system that functions as a single file system across multiple Device Managers and the Domain Manager.

The File Manager inherits the IDL interface of a File System. It then delegates tasks from the Core Framework based off of the path names to the correct mounted File System, depending on where that File System is mounted. It is also responsible for copying the appropriate Component files into the specific Device Manager’s File System as Applications are installed and launched.

11.4 Applications

Applications are software objects representing Waveforms. They are used to organize a group of Components that are linked together to accomplish a useful computational task. Applications provide a convenient way to move data around in order to achieve these different tasks by allowing for Components to easily be interchanged.

11.4.1 Application Class

Each Application contains a unique Application name and profile, which describes the Application’s configuration. This profile is a SAD file that is referenced by a File Manager.

An Application object is responsible for providing control, configuration, and status of any Application that is instantiated in the Domain. In order to accomplish this, each Application object maintains various data structures to monitor all aspects of its execution.

A list of SPD implementation IDs and a list of Process Identifiers (PIDs) are kept for each Component that makes up the Application in order to manage their life cycles. Since every Component has to be associated with at least one Device, each Component is also stored in a list with the Device that it uses, is loaded on or is executed on.

Upon completion, the Application’s releaseObject() function is responsible for various clean up tasks. Any task or process allocated on Executable Devices are stopped using the terminate() function. All memory allocated by Component instances on Loadable Devices is freed using the unload() function. Finally, any additional capacities or resources that were allocated during creation are released using the Device’s deallocateCapacity() method. These changes return the Devices to the state they were in before the Application was launched (the state of the Devices may not have changed during Application execution).

All object references to Components that make up the Application are released and all connected Ports are disconnected. Any consumers or producers that were connected to a CORBA Event Channel are removed. Finally, all Component’s naming contexts are unbound from the Naming Service.

11.4.2 SAD File

The SAD File is where information about a Waveform’s composition and configuration is stored. It is an XML file that contains tags for all of the elements required for the Application to be built and is located in: $SDRROOT/dev/waveforms/WAVE_NAME. This file is parsed by the runtime environment and used by an Application Factory to construct the desired Waveform.

Individual elements of the file include:

Within the SAD file, each Component instantiation has a unique ID, which allows support for multiple instantiations of the same Component. In this situation, each Component would have the same file reference, a unique IDs, as well as a unique name in the Naming Service that is based off of the Component’s usage name. For multiple instantiations of the same Component, the trailing digit on the usage name is simply incremented.

11.4.3 Assembly Controller and Start Order

Each Waveform has only one Assembly Controller that serves as the starting point for the Application. The Component that is marked as the Assembly Controller is responsible for delegating implementations of the inherited CF::Resource functions that include:

By default, the first Component added to a Waveform is the Assembly Controller. However, the Assembly Controller can be changed to any Component in the Waveform by right-clicking on the Component in the Waveform diagram and selecting Set As Assembly Controller from the context menu.


PIC

Figure 11.7: Assembly Controller Assignment


In the Waveform diagram, the circled number in the Component indicates the Component’s designated start order. This is the order that the start() function is called on the Components within the Waveform.

The Assembly Controller is always started first.

To modify the start order:

  1. In the Waveform diagram, right-click the Component for which you want to change the start order.
  2. Select Move Start Order Earlier to start the Component earlier.
  3. Select Move Start Order Later to start the Component later.
    PIC
    Figure 11.8: Start Order Assignment


11.4.4 Host Collocation

To address varying performance considerations, some application designs may require multiple Components be deployed on the same piece of hardware. To meet this type of requirement, in the sad.xml file, you can specify that a set of Components be collocated on a single host at runtime.

To collocate Components in the IDE:

  1. Open the Advanced section of the Palette.
  2. Select Host Collocation.
    PIC
    Figure 11.9: Select Host Collocation from the Advanced section of the Palette


  3. Drag Host Collocation onto the Diagram to create a Collocated area.
  4. Give the collocated area a name.
    PIC
    Figure 11.10: Name Host Collocation


  5. Add desired Components to the collocated area.
    PIC
    Figure 11.11: Add Components to Host Collocation


  6. Finalize other Component connections.
    PIC
    Figure 11.12: Finalize other Component connections


11.4.5 External Ports

Within the REDHAWK Framework, a particular Component’s Port can be designated as an external Port so that it is accessible to external Waveform objects. Using external Ports, a complex Waveform may be subdivided into smaller more manageable Waveforms. Marking a Port as external adds an external Ports tag in the SAD XML file containing the Component instance that owns the Port in question. Additionally, the color of the Port’s block in the diagram changes color to mark it as externally accessible. For information about marking a Port as external, refer to Section 14.4.2.3.

External Ports can be renamed in the Overview tab of the Application’s SAD file. Renaming a Port enables other Applications to access the Port with a different name instance than the one specified in the Components SCD file, thus preventing naming collision. For information about renaming an external Port, refer to Section 14.4.2.1.

11.4.6 External Properties

Individual Component Properties can be promoted as external in the Properties tab of the Application’s SAD file, which enables other Applications to access these internal Property values through configure() and query(). To prevent naming collision, the Property ID can also be assigned an external ID. If no external ID is specified, the internal Property ID from the Components PRF file is used as its external ID. For information about making a Property external, refer to Section 14.4.2.2.

11.4.7 Using the Find By Feature

A Find By represents an object within a REDHAWK Domain that will be available at runtime (when the Waveform is launched in a Domain). Find Bys contain details that describe the object. For example, the details may specify that it is a Domain manager or it is a Service with a specific name. When a Waveform is launched in a Domain, the Find By details help to locate the appropriate object, and then any connections the user specified in the Waveform are established. Those connections are sometimes directly to the object itself, or sometimes to ports on the object, depending on the context. You can search for a resource by name, a Service by name or type, or an Event Channel by name.

11.4.7.1 Find By Name

To find a resource in the domain by name:

  1. From the Palette, in the Find By folder, select Find By Name and drag it onto the diagram.

    The Find By Name dialog is displayed.


    PIC
    Figure 11.13: Find By Name


  2. Enter the name of the Component you want to find.
  3. Optionally, enter the Component’s Ports names that you want to use. For Provides Ports, enter the name and click Add Provides Port. For Uses Ports, enter the name and click Add Uses Port.
  4. Click Finish.

    The Find By Name is displayed in the diagram.

11.4.7.2 Find By Service

To find a Service in the domain:

  1. From the Palette, in the Find By folder, select Service and drag it onto the diagram. The Find By Service dialog is displayed.
    PIC
    Figure 11.14: Find By Service


  2. If you want to search for a Service Name, select the Service Name radio button and enter the Service Name you want to find.
  3. If you want to search for a Service Type, select the Service Type radio button and enter the Service Type you want to find. The Service Type indicates the interface (IDL) provided by the Service. Click Browse to select an IDL type the IDE recognizes.
  4. Optionally, enter the Component’s Ports names that you want to use. For Provides Ports, enter the name and click Add Provides Port. For Uses Ports, enter the name and click Add Uses Port.
  5. Click Finish.

    The Service Name or Service Type is displayed in the diagram.

11.4.7.3 Find By Event Channel

To find an event channel in the domain:

  1. From the Palette, in the Find By folder, select Event Channel and drag it onto the diagram.

    The Event Channel dialog is displayed.


    PIC
    Figure 11.15: Event Channel


  2. Enter the name of the Event Channel you want to find and click OK.

    The Event Channel is displayed in the diagram.

11.4.8 usesdevice Relationship

An Application may require that specific Devices are running in order for the Application to be deployed. The usesdevice relationship is a mechanism for expressing such a requirement. The usesdevice relationship also enables the Application to connect Ports of Components within the SAD file to Ports of Devices running in a Node. These specifications are handled through tags in the Application’s SAD XML, which can contain any number of usesdevice relationships. Each usesdevice relationship has a unique ID with a set of allocation Property dependencies required for the relationship to be satisfied. (For more information about allocation Properties, refer to Section 9.3.2).

The following example XML expresses the usesdevice relationship and must reside within the softwareassembly element of the SAD XML file. The usesdevicedependencies element must be the last element within the softwareassembly element.

In the above example, there are two usesdevice dependencies with IDs of uses_device_1 and uses_device_2. The first requires a Property with an ID of os that matches the value of linux. The second requires a struct with an ID of struct_alloc_prop with members long_capacity and float_capacity that have the necessary available capacity specified in the value tag.

Once these dependencies have been declared, Port connections can be made in the connections section of the SAD XML file. The following example makes two connections. The first connection is from the Port: output_port of Component_1 to the Port: input_port of the Device that satisfies the uses_device_1 relationship. The second is from the Port: output_port of the Device that satisfies the uses_device_2 relationship to the Port: input_port of Component_2.

11.5 The Application Factory

The Application Factory is responsible for the creation of Applications within a Domain. Whenever an Application is installed by the Domain Manager, an Application Factory is created from tags in the Application’s SAD file, in order to deploy Components of the Application to Devices based on their implementation dependencies.

When the create() function is called, the Application Factory uses the SPD implementation element to locate Devices that are capable of loading and executing the given Component. The Application Factory does this by first assembling a list of all of the allocation Properties required by the Components that make up its Application. It then searches through each of the candidate Devices for Properties whose kindtype is allocation and action is not external. It attempts to use that Devices allocateCapacity() function in order to compare the requested capacities with the Devices available resources.

The creation of the Application fails if the Application Factory is unable to deploy all of the Components in compliance with the Components’ dependencies and host-collocation requirements given the available Devices.

Once the resource marshaling has been successfully completed, the File Manager copies the appropriate Component files into the specific Device Manager’s File System and the Application Factory performs the load() and execute() operations in order to launch the Component on its assigned Device. It then continues to initialize, connect and configure the Components. Properties can also be overridden from the componentproperties tags in the Waveform’s SAD file.

11.6 The Device Manager

The Device Manager interface is used to manage a set of logical Devices, Services and a File System. The Device Manager is responsible for parsing the Node’s DCD XML in order to fork processes for all Devices and Services in the Node. Each process gets passed a list of command-line character strings as executable parameters that are Node-specific configuration variables read from the DCD file.

Once a child process has been forked, its reference is added to a pending list in the Device Manager, while the child process is initialized and configured (possibly with overloaded Property values). After that, it registers itself with the Device Manager, moving its reference from the pending list into a registered list. These lists allow the Device Manager to have knowledge of the status of all Devices and Services contained within its Node. Once all children have been launched, instantiated, and configured, the Device Manager connects the Devices as described by the DCD file.

The Device Manager also responds to signals from any of its child processes. Upon exit of a child, the Device Manager cleans up the bookkeeping by removing any references to the process from the pending or registered lists and unbinding its name from the Naming Service.

The Device Manager also has a signal handler for SIGINT, SIGQUIT and SIGTERM that triggers a shutdown of the Node. The Node shutdown process unregisters and calls releaseObject on all Services and Devices, kills off all of the child processes, and unbinds any remaining names, including itself, from the Naming Service.

11.6.1 Launching a Device Manager from the Command Line

To launch a Device from the command line, a Domain Manager must be up and running.

11.6.2 DCD File

The DCD file is an XML file that contains the necessary information to configure a Node, which is a specific instance of a Device Manager, as well as all Devices and Services associated with that Device Manager instance. The DCD file contains information about the Devices and Services associated with a Device Manager, where to look for a Domain Manager, and other configuration information for Devices and Services. The file is named: DeviceManager.dcd.xml and is located at: $SDRROOT/dev/nodes/NODE_NAME.

Information that is covered in this file includes:

11.6.3 Nodes

Nodes are the collection of Devices, Services, and connections associated with a single Device Manager instance. There is always only one Device Manager per Node. Nodes are deployed on a Domain to give the Applications the ability to communicate with the systems hardware. Upon creation of an Application, the Application Factory attempts to place each required Component on a Device that is deployed in a Node.

11.6.4 Devices

In REDHAWK, Devices are specialized Components that perform command and control of hardware. They are proxies that are able to run in the Domain and provide a single point to interact with one or more pieces of physical hardware.

Devices communicate with various pieces of hardware in order to keep track of their capacities. When Waveforms are deployed and the hardware resources are allocated, the Devices keep track of the amount of any specific resource that was used, and what is still currently available. This is a important because it keeps Components from attempting to over-allocate on any one piece of hardware.

11.6.4.1 Using Valgrind to Debug Devices

The Device Manager supports launching Devices using Valgrind, an open source tool that helps detect memory errors and leaks.

The VALGRIND environment variable controls this behavior:

Valgrind log files are written to the Device’s cache directory (e.g., $SDRROOT/dev/.MyNode/MyDevice). The log file name follows the pattern valgrind.<PID>.log, where PID is the process ID of the Device.

11.7 The Allocation Manager

The Allocation Manager provides a single point for creating, inspecting, and delegating allocations. When using the regular Application deployment mechanism, any allocation associated with a particular Application is available for inspection on the Allocation Manager. The Allocation Manager can also be used by Components or other programs to create new allocations. Whichever allocation was made through the Allocation Manager is available for inspection.

A Domain Manager can register with other Domain Managers. If a Domain Manager is registered with another Domain Manager, then any usesdevice relationship allocation that cannot be satisfied by the Domain Manager is delegated to the remote Domain Managers.

11.8 The Connection Manager

The Connection Manager provides a single point for creation and inspection of connections between Domain objects. Connections between Domain objects can be defined on the Connection Manager irrespective of whether or not these objects are currently deployed. If one or more of the endpoints defined in a connection are not available, the connection is pending. Connections are resolved anytime Domain objects enter or leave the Domain

Endpoints can be Applications, Devices, Services, Event Channels, or CORBA object references.

11.9 Events

Events are heavily leveraged by REDHAWK to provide system awareness and exchange both synchronous and asynchronous data. This chapter describes the mechanics of creating and consuming Events as well as standard Event types defined in REDHAWK and how they are used. The methodology used to exchange synchronous and asynchronous data, although reliant on Events as the communications mechanism, is discussed in Section 5.9.

11.9.1 Event Definition

CORBA defines an interface for the transport of Events as well as an interface for the creation of Event Channels that can support a publish/subscribe pattern; within REDHAWK, publishers are often described as producers, and subscribers are often described as consumers.

In REDHAWK, an Event is defined as the payload sent on a single call to the push() function in the PushConsumer interface of the CosEventComm IDL module.

The PushConsumer interface is as follows:

The description of the Event Channel interface and its use is complicated but luckily unnecessary for the use of Events in REDHAWK. The main thing to be aware of regarding channels is that they provide a logical association between a plain text string (channel name) and an object that implements the interfaces necessary to interconnect producers and consumers, CosEventChannelAdmin::EventChannel. The EventChannel interface allows a producer or consumer to register itself with the Event Channel. This registration process gives the producer a reference to a virtual consumer where Events can be pushed (recall that at the end of the day, CORBA is just an RPC mechanism). The registration process allows the consumer to give a reference to itself to a virtual producer, so that when an Event becomes available, the correct function is invoked in the consumer. It is the job of the implementer of the Event Channel interface, also known as an Event Service, to maintain the registration interface as well as the different virtual producers and consumers necessary to re-direct all Events to their appropriate destinations. The program omniEvents implements the Event Channel interface and enables the publish/subscribe pattern as described above; REDHAWK uses omniEvents as its Event Service.

An interesting aspect of the EventChannel interface is that there is no reason why that interface is implemented on a single central Event broker. It is possible to create a consumer that implements both a consumer interface and the Event Channel interface. This allows that consumer to consume Events either directly from a producer or indirectly through an Event Service. While a central Event broker like omniEvents allows for the fluid addition of producers and consumers into the Domain, the inherent latency to the distribution of the Event can be significant (a single call for the publishing of the Event, an intermediate process queuing that Event, and then one or more pushes for the distribution of the Event to one or more consumers). On the other hand, a point-to-point connection between a producer and a consumer removes the intermediary broker and enables low-latency messaging between Components. In REDHAWK, low-latency point-to-point Events are used only on Messages, which are described in Section 5.9.

11.9.2 Standard REDHAWK Events

REDHAWK has defined several standard Event types that can be used to monitor the overall state of a Domain or individual Components. The system management Events are sent over the Domain management channels. Individual Component Events are associated with Property changes.

REDHAWK defines an Outgoing Domain Management (ODM) channel as well as an Incoming Domain Management (IDM) channel. The ODM channel contains Events that are generated by the Domain Manager which indicate the addition or removal of entities to and from the Domain. The IDM channel contains Events that are generated by Devices which indicate changes in the state of a Device.

11.9.2.1 ODM Channel

The ODM channel contains Event types used to describe the addition or removal of objects from the Domain:

Either Event contains information as to who had something added/removed to/from it, the ID of the entity that was added/removed, the name of the entity that was added/removed, and the category of item that was added/removed. In the case of an added object, the IOR (stringified pointer to the object) is included in the Event.

The category of item that was added or removed is of type SourceCategoryType, which is defined as:

The ODM channel can also contain an Event type used to describe the state change of a resource, like an Application:

where ExtendedEvent::ResourceStateChangeType is defined as:

11.9.2.2 IDM Channel

The IDM channel can contain a StateChangeEventType Event or a AbnormalComponentTerminationEventType Event. The StateChangeEventType Event is defined as:

The producerId and sourceId of the Event type are redundant; they are both the ID of the Device that is issuing the Event.

The StateChangeCategoryType and StateChangeType are:

The two enumerated types are closely linked; an ADMINISTRATIVE_STATE_EVENT can only contain states LOCKED, UNLOCKED, and SHUTTING_DOWN, while an OPERATIONAL_STATE_EVENT can only contain states ENABLED and DISABLED, and a USAGE_STATE_EVENT can only contain states IDLE, ACTIVE, or BUSY.

The AbnormalComponentTerminationEventType Event is defined as:

This Event is triggered when a Component abnormally terminates. The Event contains the Device id that is producing the Event, the Component id that terminated abnormally, and the Application id that hosts that Component.

11.9.2.3 Property Change Events

Whenever a property changes on a Component or Device, either through the internal update of the Component property or through an external configuration update, an event can be triggered. Any consumer can be registered onto any Component or Device to listen to any arbitrary set of Properties that the Component or Device may have.

The event type is PropertyChangeEvent, which is defined as:

11.9.3 Cleaning up the Event Service

Sometimes the system will fail in ways that the Event Service (omniEvents) will no longer be synchronized with the Domain. When this happens, two utilities have been included with REDHAWK to help understand the state of the Event Service and clean it up if necessary.

The first tool is eventl, which lists all of the Events that are currently being handled by the Event Service. The other tool is rmeventall, which cleans up all of the Event Channels that the Event Service is currently supporting.

11.9.4 Consuming Events

Event consumption is meant as a system-level monitoring process. Therefore, REDHAWK does not include Component Ports that allow the consumption of these Events. To monitor Events over a given channel, a simple API is available. The Domain Manager contains the function registerWithEventChannel() to register a consumer to a given channel and unregisterFromEventChannel() to unregister a consumer from an Event Channel.

A command-line tool is available that registers with Event Channels and displays the contents of the channel, eventviewer. The arguments to eventviewer are the name of the Domain and the name of the channel.

An example of the use of eventviewer is described below:

  1. Start a Domain Manager:
  2. In a new terminal, attach the eventviewer to the Domain’s ODM channel:
  3. In a new terminal, start a Device Manager:
  4. On the Eventviewer terminal, the Device Manager and Device registration are shown:
  5. Shutdown the Device Manager (Ctrl+C on the Device Manager terminal)
  6. On the Eventviewer terminal, the Device and Device Manager unregistration is displayed:

11.9.5 Writing Your Own Event Consumer

In CORBA’s Event API, Messages are passed as an CORBA::Any type, so when the Event is consumed from an Event Channel, it arrives as a CORBA::Any type. The Application eventviewer contains an example of how to create an Event consumer.

The consumer object is an object that implements the PushConsumer interface.

In Python, the definition of such a class is:

In the above example, the call to any.from_any converts from a CORBA::Any type to a Python dictionary.

An object of the class Consumer needs to be instantiated and given to the Domain Manager. In Python, the easiest way to access a running Domain is to use the REDHAWK runtime package (a thorough description of the REDHAWK runtime package is available in Chapter 12); in the case of a Domain called REDHAWK_DEV, the process needed to associate this consumer with the Event Channel is:

In the example shown above, the consumer is attached to the ODM_Channel on the Domain REDHAWK_DEV. The registration ID is some string that can be used to uniquely identify this registration.

Using this ID, to unregister the code the following method is invoked:

11.10 The Event Channel Manager

The Event Channel Manager provides a single point for creation and inspection of Event Channels on the Domain. It also provides an interface for users to register publishers or subscribers to any of the available Event Channels.


Creative Commons License
REDHAWK Documentation is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.