#pragma priority documentation
mendell at ca.ibm.com
mendell at ca.ibm.com
Thu Jul 8 19:21:36 UTC 1999
This is from our User's Guides. I hope it looks good when you get it.
The #pragma priority directive specifies the order in which static objects
are to be initialized at run time.
Note: This directive is valid for C++ programs only.
#pragma priority(n)
Where n is an integer literal in the range of INT_MIN to INT_MAX. The
default value is 0. A negative value indicates a higher priority; a
positive value indicates a lower priority.
The first 1024 priorities (INT_MIN to INT_MIN + 1023) are reserved for use
by the compiler and its libraries. The priority value specified applies
to all runtime static initialization in the current compilation unit.
Any global object declared before another object in a file is constructed
first. Use #pragma priority to specify the construction order of objects
across files.
To ensure that the objects are always constructed from top to bottom in a
file, the compiler enforces the restriction that the priority specified
all objects before and all objects after it until the next #pragma is at
that priority.
There is also a command line option -qpriority=N, which is equivalent to
#pragma priority (N) as the first statement in the program.
makeC++SharedLib Command
This section describes the makeC++SharedLib command and provides an example of
how to use it to make two shared libraries. It describes how to combine these
two files in a library using the ar command so that object initialization takes
place in the specified order.
+-----------------+
V |
>>-- makeC++SharedLib --+--------------------+---+-------------+-+--->
+- -o shared_file.o -+ +- -bOptions -+
+-------------------+ +------------------+
V | V |
>------+--------------+--+-------+-------------+--+-- -p priority --->
+- -L lib_dir -+ +- -llibrary -+
+-----------------------+ +-----------------------+
V | V |
>------+------------------+--+---------+------------------+--+------->
+- -I import_list -+ +- -E export_list -+
+----------+ +----------+
V | V |
>----+-----------+---+-----------+----- file.o -+------- file.a -+--><
+- -e file -+ +- -n name -+
Options
|---------------->
|makeC++SharedLib|
|---------------->
>------------------------------------------------------------------------|
|Is the path name for the makeC++SharedLib command that constructs the |
|shared library file. |
>------------------------------------------------------------------------|
|---------------->
|-oshared_file.o |
|---------------->
>------------------------------------------------------------------------|
|Is the name of the file that will hold the shared file information. The |
|default is shr.o. |
>------------------------------------------------------------------------|
|---------------->
|-bOptions |
|---------------->
>------------------------------------------------------------------------|
|Uses the -b binder options of the ld command. |
>------------------------------------------------------------------------|
|---------------->
|-Llib_dir |
|---------------->
>------------------------------------------------------------------------|
|Uses the -L option of the ld command to add the directory lib_dir to the|
|list of directories to be searched for unresolved symbols. The ld |
|command is described in the AIX Version 4 Commands Reference. |
>------------------------------------------------------------------------|
|---------------->
|-llibrary |
|---------------->
>------------------------------------------------------------------------|
|Adds library to the list of libraries to be searched for unresolved |
|symbols. |
>------------------------------------------------------------------------|
|---------------->
|-p priority |
|---------------->
>------------------------------------------------------------------------|
|Specifies the priority level for the file. priority may be any number |
|from -214782623 (highest priority-initialized first) to 214783647 |
|(lowest priority-initialized last). Numbers from -214783648 to |
|-214782624 are reserved for system use. |
>------------------------------------------------------------------------|
|---------------->
|-I import_list |
|---------------->
>------------------------------------------------------------------------|
|Uses the -bI option of the ld command to resolve the list of symbols in |
|the file import_list that can be resolved by the binder. |
>------------------------------------------------------------------------|
|---------------->
|-E export_list |
|---------------->
>------------------------------------------------------------------------|
|Uses the -bE option of the ld command to export the external symbols in |
|the export_list file. If you do not specify -E export_list, a list of |
|all global symbols is generated. |
>------------------------------------------------------------------------|
|---------------->
|-e file |
|---------------->
>------------------------------------------------------------------------|
|Saves in file the list computed by -E export_list. |
>------------------------------------------------------------------------|
|---------------->
|-n name |
|---------------->
>------------------------------------------------------------------------|
|Sets the entry name for the shared executable to name. This is |
|equivalent to using the command ld -e name |
>------------------------------------------------------------------------|
|---------------->
|-X mode |
|---------------->
>------------------------------------------------------------------------|
|Specifies the type of object file makeC++SharedLib should create. The |
|mode must be either 32, which processes only 32-bit object files, or 64,|
|which processes only 64-bit object files. The default is to process |
|32-bit object files (ignore 64-bit objects). The mode can also be set |
|with the OBJECT_MODE environment variable. For example, OBJECT_MODE=64 |
|causes makeC++SharedLib to process any 64-bit objects and ignore 32-bit |
|objects. The -X flag overrides the OBJECT_MODE variable. |
>------------------------------------------------------------------------|
|---------------->
|file.o |
|---------------->
>------------------------------------------------------------------------|
|Is an object file to be put into the shared library. |
>------------------------------------------------------------------------|
|---------------->
|file.a |
|---------------->
>------------------------------------------------------------------------|
|Is an archive file to be put into the shared library. |
>------------------------------------------------------------------------|
Example
The following example shows how to construct two shared libraries using the
makeC++SharedLib command, and then use the AIX ar command to combine these
libraries along with a file that contains the main function so that objects are
initialized in the specified order.
The drawing below shows how the objects in this example are arranged in various
files.
|---------+--------------------------------+-+----------->
| | | | fish.o|
| | | | (priority|
| | | | 100)|
|---------+--------------------------------+-+----------->
>--------------------------------|
| |
| |
| |
| |
| |
| |
| fresh.C|
| |
| |
| |
| #pragma priority(-80) |
| ... |
| class trout A |
| ... |
| #pragma priority(500) |
| ... |
| class bass B |
| |
| salt.C|
| |
| |
| |
| ... |
| #pragma priority(-200) |
| ... |
| class shark S |
| ... |
| #pragma priority(10) |
| ... |
| class tuna T |
| |
| |
| |
>--------------------------------|
|---------+--------------------------------+-+----------->
|animals.o| | |myprogram.C|
|(priority| | | (priority|
|40) | | | 0)|
| | | | |
| | | | |
| | | | |
| | house.C| | |
| | | | |
| | | | |
| | | | |
| | #pragma priority(20) | | |
| | ... | | |
| | class dog D | | |
| | ... | | |
| | #pragma priority(100) | | |
| | ... | | |
| | class cat C | | |
| | | | |
| | farm.C| | |
| | | | |
| | | | |
| | | | |
| | ... | | |
| | class horse H | | |
| | ... | | |
| | #pragma priority(500) | | |
| | ... | | |
| | class cow W | | |
| | | | |
| | zoo.C| | |
| | | | |
| | | | |
| | | | |
| | ... | | |
| | class lion L | | |
| | ... | | |
| | #pragma priority(50) | | |
| | ... | | |
| | class zebra Z | | |
| | ... | | |
| | | | |
| | | | |
| | | | |
|---------+--------------------------------+-+----------->
>--------------------------------|
| |
| |
| |
| ... |
| main () { |
| ... |
| class Cage CAGE |
| ... |
| |
| ... |
| |
>--------------------------------|
The first part of this example shows how to use makeC++SharedLib along with the
-qpriority=N option and the #pragma priority(N) directive to specify the
initialization order for objects in these files.
The example shows how to make two shared libraries: animals.o containing object
files compiled from house.C, farm.C, and zoo.C, and fish.o containing object
files compiled from fresh.C and salt.C.
The example shows how to specify priorities and use the ar command so that all
the objects in fish.o are initialized before the objects in myprogram.o, and all
the objects in animals.o are initialized after the objects in myprogram.o.
Within animals.o, the objects in zoo.C are initialized before the objects in
house.C and farm.C.
To specify this initialization order, follow these steps:
1. Develop an initialization order for the objects in house.C, farm.C,
and zoo.C:
a. To ensure that the object lion L in zoo.C is initialized before
any other objects in either of the other two files, compile zoo.C
using a -qpriority=N option with N less than zero so both objects have
a priority number less than any other objects in farm.C and house.C:
xlC zoo.C -c -qpriority=-50
b. Compile the house.C and farm.C files without specifying the
-qpriority=N option (so N=0) so objects within the files retain the
priority numbers specified by their #pragma priority(N) directives:
xlC house.C farm.C -c
c. Combine these three files in a shared library. Use
makeC++SharedLib to construct a library animals.o with a priority of
40:
makeC++SharedLib -o animals.o -p 40 house.o farm.o zoo.o
2. Develop an initialization order for the objects in fresh.C, and
salt.C:
a. Compile the fresh.C and salt.C files:
xlC fresh.C salt.C -c
b. To assure that all objects in fresh.C and salt.C are initialized
before any other objects, use makeC++SharedLib to construct a library
fish.o with a priority of -100.
makeC++SharedLib -o fish.o -p -100 fresh.o salt.o
Because the shared library fish.o has a lower priority number (-100)
than animals.o (40), when the files are placed in an archive file with
the ar command, their objects are initialized first.
3. Compile myprogram.C that contains the function main to produce an
object file myprogram.o. By not specifying a priority, this file is
compiled with a default priority of zero, and the objects in main have a
priority of zero.
xlC myprogram.C -c
4. To create a library that contains the two shared libraries, and the
program myprogram.o that contains the function main, so that the objects
are initialized in the order you have specified, you use the ar command. To
produce an archive file, prio_lib.a, enter the command:
ar rv prio_lib.a animals.o fish.o myprogram.o
where:
|----------->
|rv |
|----------->
>----------------------------------------------------------------------------|
|Are two ar options. r replaces a named file if it already appears in the |
|library, and v writes to standard output a file-by-file description of the |
|making of the new library. |
>----------------------------------------------------------------------------|
|----------->
|prio_lib.a |
|----------->
>----------------------------------------------------------------------------|
|Is the name you specified for the archive file that will contain the shared |
|library files and their priority levels. |
>----------------------------------------------------------------------------|
|----------->
|animals.o |
|fish.o |
|----------->
>----------------------------------------------------------------------------|
|Are the two shared files you created with makeC++SharedLib. |
>----------------------------------------------------------------------------|
|----------->
|myprogram.o|
| |
|----------->
>----------------------------------------------------------------------------|
|Is the name of the file that contains the function main. |
>----------------------------------------------------------------------------|
The order of initialization of the objects is shown in the following table.
|-----------+--------+---------->
| | | |
|-----------+--------+---------->
>-----------------------------------------------------------|
| Order of Initialization of Objects in priolib.a |
>-----------------------------------------------------------|
|-----------+--------+---------->
| File | Class | Priority |
| | Object | Value |
|-----------+--------+---------->
>-----------------------------------------------------------|
| Comment |
>-----------------------------------------------------------|
|-----------+--------+---------->
| | | -100 |
|-----------+--------+---------->
>-----------------------------------------------------------|
| All objects in "fish.o" are initialized first because they|
| are in a library prepared with makeC++SharedLib -p -100 |
| (lowest priority number, -p -100, specified for any files |
| in this compilation) |
>-----------------------------------------------------------|
|-----------+--------+---------->
| | "shark | -100(-200|
| | S" | ) |
|-----------+--------+---------->
>-----------------------------------------------------------|
| Initialized first in "fish.o" because within file, #pragma|
| priority(-200) |
>-----------------------------------------------------------|
|-----------+--------+---------->
| | "trout | -100(-80)|
| | A" | |
|-----------+--------+---------->
>-----------------------------------------------------------|
| #pragma priority(-80) |
>-----------------------------------------------------------|
|-----------+--------+---------->
| | "tuna | -100(10) |
| | T" | |
|-----------+--------+---------->
>-----------------------------------------------------------|
| #pragma priority(10) |
>-----------------------------------------------------------|
|-----------+--------+---------->
| "fish.o" | "bass | -100(500)|
| | B" | |
|-----------+--------+---------->
>-----------------------------------------------------------|
| #pragma priority(500) |
>-----------------------------------------------------------|
|-----------+--------+---------->
| | | 0 |
|-----------+--------+---------->
>-----------------------------------------------------------|
| File generated with no priority specifications; default is|
| 0 |
>-----------------------------------------------------------|
|-----------+--------+---------->
| "myprog.o"| "CAGE" | 0(0) |
|-----------+--------+---------->
>-----------------------------------------------------------|
| Object generated in main with no priority specifications; |
| default is 0 |
>-----------------------------------------------------------|
|-----------+--------+---------->
| | | 40 |
|-----------+--------+---------->
>-----------------------------------------------------------|
| File generated with makeC++SharedLib with -p 40 |
>-----------------------------------------------------------|
|-----------+--------+---------->
| | "lion | 40(-50) |
| | L" | |
|-----------+--------+---------->
>-----------------------------------------------------------|
| Initialized first in file "animals.o" compiled with |
| -qpriority=-50 |
>-----------------------------------------------------------|
|-----------+--------+---------->
| | "horse | 40(0) |
| | H" | |
|-----------+--------+---------->
>-----------------------------------------------------------|
| Follows with priority of 0 (since -qpriority=N not |
| specified at compilation and no #pragma priority(N) |
| directive) |
>-----------------------------------------------------------|
|-----------+--------+---------->
| | "dog D"| 40(20) |
|-----------+--------+---------->
>-----------------------------------------------------------|
| Next priority number (specified by #pragma priority(20)) |
>-----------------------------------------------------------|
|-----------+--------+---------->
| | "zebra | 40(50) |
| | N" | |
|-----------+--------+---------->
>-----------------------------------------------------------|
| Next priority number from #pragma priority(50) |
>-----------------------------------------------------------|
|-----------+--------+---------->
| | "cat C"| 40(100) |
| | | |
|-----------+--------+---------->
>-----------------------------------------------------------|
| Next priority number from #pragma priority(100) |
>-----------------------------------------------------------|
|-----------+--------+---------->
| "animals.o| "cow W"| 40(500) |
| " | | |
|-----------+--------+---------->
>-----------------------------------------------------------|
| Next priority number from #pragma priority(500) |
| (Initialized last) |
>-----------------------------------------------------------|
5. To produce an executable file, animal_time, so that the objects are
initialized in the order you have specified, enter:
xlC prio_lib.a -oanimal_time
You can place both nonshared and shared files with different priority
levels in the same archive library using the AIX ar command.
More information about the cxx-abi-dev
mailing list