A. Platform-Specific Information for the Run-Time Libraries

The GNAT run-time implementation may vary with respect to both the underlying threads library and the exception handling scheme. For threads support, one or more of the following are supplied:

• native threads library, a binding to the thread package from the underlying operating system

• pthreads library (Sparc Solaris only), a binding to the Solaris POSIX thread package

For exception handling, either or both of two models are supplied:

• Zero-Cost Exceptions ("ZCX"),(1) which uses binder-generated tables that are interrogated at run time to locate a handler

• setjmp / longjmp ("SJLJ"), which uses dynamically-set data to establish the set of handlers

This appendix summarizes which combinations of threads and exception support are supplied on various GNAT platforms. It then shows how to select a particular library either permanently or temporarily, explains the properties of (and tradeoffs among) the various threads libraries, and provides some additional information about several specific platforms.

A.1 Summary of Run-Time Configurations
A.2 Specifying a Run-Time Library
A.3 Choosing the Scheduling Policy
A.4 Solaris-Specific Considerations
A.5 Linux-Specific Considerations
A.6 AIX-Specific Considerations
A.7 RTX-Specific Considerations
A.8 HP-UX-Specific Considerations

A.1 Summary of Run-Time Configurations

alpha-openvms
rts-native (default)
Tasking	native VMS threads
Exceptions	ZCX
rts-sjlj
Tasking	native TRU64 threads
Exceptions	SJLJ
ia64-hp_linux
rts-native (default)
Tasking	pthread library
Exceptions	ZCX
ia64-hpux
rts-native (default)
Tasking	native HP-UX threads
Exceptions	SJLJ
ia64-openvms
rts-native (default)
Tasking	native VMS threads
Exceptions	ZCX
ia64-sgi_linux
rts-native (default)
Tasking	pthread library
Exceptions	ZCX
pa-hpux
rts-native (default)
Tasking	native HP-UX threads
Exceptions	ZCX
rts-sjlj
Tasking	native HP-UX threads
Exceptions	SJLJ
ppc-aix
rts-native (default)
Tasking	native AIX threads
Exceptions	ZCX
rts-sjlj
Tasking	native AIX threads
Exceptions	SJLJ
ppc-darwin
rts-native (default)
Tasking	native MacOS threads
Exceptions	ZCX
sparc-solaris
rts-native (default)
Tasking	native Solaris threads library
Exceptions	ZCX
rts-pthread
Tasking	pthread library
Exceptions	ZCX
rts-sjlj
Tasking	native Solaris threads library
Exceptions	SJLJ
sparc64-solaris
rts-native (default)
Tasking	native Solaris threads library
Exceptions	ZCX
x86-linux
rts-native (default)
Tasking	pthread library
Exceptions	ZCX
rts-sjlj
Tasking	pthread library
Exceptions	SJLJ
x86-lynx
rts-native (default)
Tasking	native LynxOS threads
Exceptions	SJLJ
x86-solaris
rts-native (default)
Tasking	native Solaris threads
Exceptions	ZCX
rts-sjlj
Tasking	native Solaris threads library
Exceptions	SJLJ
x86-windows
rts-native (default)
Tasking	native Win32 threads
Exceptions	ZCX
rts-sjlj
Tasking	native Win32 threads
Exceptions	SJLJ
x86-windows-rtx
rts-rtx-rtss (default)
Tasking	RTX real-time subsystem RTSS threads (kernel mode)
Exceptions	SJLJ
rts-rtx-w32
Tasking	RTX Win32 threads (user mode)
Exceptions	ZCX
x86_64-linux
rts-native (default)
Tasking	pthread library
Exceptions	ZCX
rts-sjlj
Tasking	pthread library
Exceptions	SJLJ

A.2 Specifying a Run-Time Library

The `adainclude' subdirectory containing the sources of the GNAT run-time library, and the `adalib' subdirectory containing the `ALI' files and the static and/or shared GNAT library, are located in the gcc target-dependent area:

target=$prefix/lib/gcc/gcc-dumpmachine/gcc-dumpversion/

As indicated above, on some platforms several run-time libraries are supplied. These libraries are installed in the target dependent area and contain a complete source and binary subdirectory. The detailed description below explains the differences between the different libraries in terms of their thread support.

The default run-time library (when GNAT is installed) is rts-native. This default run time is selected by the means of soft links. For example on x86-linux:

$(target-dir) | +--- adainclude----------+ | | +--- adalib-----------+ | | | | +--- rts-native | | | | | | | +--- adainclude <---+ | | | | +--- adalib <----+ | +--- rts-sjlj | +--- adainclude | +--- adalib

If the rts-sjlj library is to be selected on a permanent basis, these soft links can be modified with the following commands:

$ cd $target $ rm -f adainclude adalib $ ln -s rts-sjlj/adainclude adainclude $ ln -s rts-sjlj/adalib adalib

Alternatively, you can specify `rts-sjlj/adainclude' in the file `$target/ada_source_path' and `rts-sjlj/adalib' in `$target/ada_object_path'.

Selecting another run-time library temporarily can be achieved by using the `--RTS' switch, e.g., `--RTS=sjlj'

A.3 Choosing the Scheduling Policy

When using a POSIX threads implementation, you have a choice of several scheduling policies: SCHED_FIFO, SCHED_RR and SCHED_OTHER. Typically, the default is SCHED_OTHER, while using SCHED_FIFO or SCHED_RR requires special (e.g., root) privileges.

By default, GNAT uses the SCHED_OTHER policy. To specify SCHED_FIFO, you can use one of the following:

• pragma Time_Slice (0.0)
• the corresponding binder option `-T0'
• pragma Task_Dispatching_Policy (FIFO_Within_Priorities)

To specify SCHED_RR, you should use pragma Time_Slice with a value greater than 0.0, or else use the corresponding `-T' binder option.

A.4 Solaris-Specific Considerations

This section addresses some topics related to the various threads libraries on Sparc Solaris.

A.4.1 Solaris Threads Issues

A.4.1 Solaris Threads Issues

GNAT under Solaris/Sparc 32 bits comes with an alternate tasking run-time library based on POSIX threads -- rts-pthread. This run-time library has the advantage of being mostly shared across all POSIX-compliant thread implementations, and it also provides under Solaris 8 the PTHREAD_PRIO_INHERIT and PTHREAD_PRIO_PROTECT semantics that can be selected using the predefined pragma Locking_Policy with respectively Inheritance_Locking and Ceiling_Locking as the policy.

As explained above, the native run-time library is based on the Solaris thread library (libthread) and is the default library.

When the Solaris threads library is used (this is the default), programs compiled with GNAT can automatically take advantage of and can thus execute on multiple processors. The user can alternatively specify a processor on which the program should run to emulate a single-processor system. The multiprocessor / uniprocessor choice is made by setting the environment variable GNAT_PROCESSOR to one of the following:

-2

Use the default configuration (run the program on all available processors) - this is the same as having GNAT_PROCESSOR unset

-1

Let the run-time implementation choose one processor and run the program on that processor

0 .. Last_Proc

Run the program on the specified processor. Last_Proc is equal to _SC_NPROCESSORS_CONF - 1 (where _SC_NPROCESSORS_CONF is a system variable).

A.5 Linux-Specific Considerations

On GNU/Linux without NPTL support (usually system with GNU C Library older than 2.3), the signal model is not POSIX compliant, which means that to send a signal to the process, you need to send the signal to all threads, e.g. by using killpg().

A.6 AIX-Specific Considerations

On AIX, the resolver library initializes some internal structure on the first call to get*by* functions, which are used to implement GNAT.Sockets.Get_Host_By_Name and GNAT.Sockets.Get_Host_By_Address. If such initialization occurs within an Ada task, and the stack size for the task is the default size, a stack overflow may occur.

To avoid this overflow, the user should either ensure that the first call to GNAT.Sockets.Get_Host_By_Name or GNAT.Sockets.Get_Host_By_Addrss occurs in the environment task, or use pragma Storage_Size to specify a sufficiently large size for the stack of the task that contains this call.

A.7 RTX-Specific Considerations

The Real-time Extension (RTX) to Windows is based on the Windows Win32 API. Applications can be built to work in two different modes:

• Windows executables that run in Ring 3 to utilize memory protection (rts-rtx-w32).

• Real-time subsystem (RTSS) executables that run in Ring 0, where performance can be optimized with RTSS applications taking precedent over all Windows applications (rts-rtx-rtss). This mode requires the Microsoft linker to handle RTSS libraries.

A.8 HP-UX-Specific Considerations

On HP-UX, appropriate privileges are required to change the scheduling parameters of a task. The calling process must have appropriate privileges or be a member of a group having PRIV_RTSCHED access to successfully change the scheduling parameters.

By default, GNAT uses the SCHED_HPUX policy. To have access to the priority range 0-31 either the FIFO_Within_Priorities or the Round_Robin_Within_Priorities scheduling policies need to be set.

To specify the FIFO_Within_Priorities scheduling policy you can use one of the following:

• pragma Time_Slice (0.0)
• the corresponding binder option `-T0'
• pragma Task_Dispatching_Policy (FIFO_Within_Priorities)

To specify the Round_Robin_Within_Priorities, scheduling policy you should use pragma Time_Slice with a value greater than 0.0, or use the corresponding `-T' binder option, or set the pragma Task_Dispatching_Policy (Round_Robin_Within_Priorities).