GNAT GPL User's Guide: Platform-Specific Information for the Run-Time Libraries

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 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 |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 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'`

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 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 |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 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).

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 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()`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 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)`.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html