test

ChorusOS 4.0 Introduction

Application Programming Interfaces

This section provides an overview of all programming interfaces available for applications developed for the ChorusOS operating system. The programming interface may differ from one program to another depending on:

Naming Conventions

Library names in the ChorusOS operating system use the following conventions with regard to their suffixes:

.u.a These libraries can only be used to build actors that will be loaded in a user address space.
.s.a These libraries can only be used to build actors that will be loaded in the supervisor address space.
.a These libraries can be used to build any type of actor.

Note -

When a library has both a user and supervisor version, it will be referred to using the .a suffix only.

All header file and library pathnames listed in the next subsections are related to the installation path of your ChorusOS delivery, typically /opt/SUNWconn/SEW/4.0/chorus-<target>.

Basic Environment APIs

The programming environment of basic actors consists of the following interfaces:

All routines implementing these APIs have been grouped into two libraries:

kernel/lib/embedded/libebd.u.a for user actors
kernel/lib/embedded/libebd.s.a  for supervisor actors

ChorusOS actors using the Basic Environment API are called embedded actors.

Extended Environment API

The programming environment of extended actors consists of the following interfaces:

All routines implementing these APIs have been grouped into one library:

os/lib/classix/libcx.a for user and supervisor actors

Note -

An extended supervisor actor should not use the svExcHandler() call as an extended actor inherits the Actor Manager exception handler.

Other APIs

Other APIs are provided with the ChorusOS operating system. Depending on their nature, they may be available to both basic and extended environments or restricted to a single environment. The following subsections give a description of the libraries implementing these APIs.

POSIX Micro Real-time Profile API

Routines implementing the MRTP (Micro Real-time Profile) API are included within the libcx and libebd libraries. They are available to both basic and extended actors.

Mathematical API

Routines implementing the Mathematical API are packaged in an independent library kernel/lib/libm/libm.a. This library is available to both basic and extended actors.

Sun RPC API

Routines implementing the Sun RPC API are packaged in an independent library os/lib/classix/librpc.a which is not thread-safe. This API is restricted to extended actors.

GNU 2.7.1 C++ API

The C++ library os/lib/CC/libC.a provides support for C++ applications with a complete and thread-safe library package. Every service offered by libC.a ensures that shared data is only accessed after signaling the relevant synchronization objects.

To allow atomic manipulation of any stream class (iostream or fstream for example), the API of libC.a has been extended with the following two services:

The ios::lock()service is used to lock any stream class object. The ios::unlock() service is used to unlock any stream class object. All services called upon a given stream object StrObj which are preceded by StrObj.lock() and followed by StrObj.unlock() are executed in an atomic way. It is guaranteed that no other thread can access StrObj as long as the lock is on.

An I/O stream object can be locked in two ways. For example, if cout is an I/O stream object: 

cout.lock();  
cout << "atomic " << "output";  
... (any other operation on cout)  
cout.unlock();
In this case the member function ios::lock() is called.

The following syntax could also be used:

cout << lock << "atomic " << "output" << unlock;

Embedded C++ actors can be linked with os/lib/CC/libC.a if they do not make use of the iostream and fstream packages.

Multithreading

The libebd.a, libcx.a, libm.a and libC.a libraries have been made thread-safe in order to support multithreaded actors. This is managed by the library in the following way:

Defining errno as one global variable for the actor is not suitable for multithreaded actors as situations can arise where a thread, examining errno on return from a failed system call, concludes that the call failed for the wrong reason because the global errno was changed by another system call in another thread in the meantime. Some programs also test errno rather than system call return values to detect errors.

To avoid this, the header file errno.h, exported by the extended environment, should be included in any source file using errno. This will result in a separate value for errno for each thread.

Header Files

The ChorusOS operating system header files are packaged in five different directories:

Typical ChorusOS operating system applications use header files of the include/chorus and include/posix directories (and also include/CC for applications using the GNU 2.7.1 C++ API).

Developing personality servers (such as servers implementing a UNIX personality) on a ChorusOS operating system needs extra care in order to avoid conflicts between data types declared by ChorusOS operating system header files, and data types declared by the server's header files. These servers should be restricted to header files of the include/chorus and include/stdc directories and use the _CHO_POSIX_TYPES_NOTDEF compile option.