4. Building an application with PolyORB¶
4.1. Compile-time configuration¶
The user may configure some elements of a PolyORB application at compile-time.
4.1.1. Tasking runtimes¶
PolyORB provides several tasking runtimes. The user may select the most appropriate one, depending on application requirements. The tasking runtimes determine the constructs PolyORB may use for its internal synchronizations.
No_Tasking: There is no dependency on the Ada tasking runtime, middleware is mono-task.
Full_Tasking: Middleware uses Ada tasking constructs, middleware can be configured for multi-tasking.
Ravenscar : Middleware uses Ada tasking constructs, with the limitations of the Ravenscar profile :cite:`burns98ravenscar`. Middleware can be configured for multi-tasking. .. index:: Ravenscar
See Tasking model in PolyORB for more information on this point.
4.1.2. Middleware tasking policies¶
PolyORB provides several tasking policies. A tasking policy defines how tasks are used by the middleware to process incoming requests.
No_Tasking: There is only one task in middleware, processing all requests.
Thread_Per_Session: One task monitors communication entities. One task is spawned for each active connection. This task handles all incoming requests on this connection.
Thread_Per_Request: One task monitors communication entities. One task is spawned for each incoming request.
Thread_Pool: A set of tasks cooperate to handle all incoming requests.
See Tasking model in PolyORB for more information on this point.
4.1.3. Sample files¶
PolyORB provides a set of predefined setup packages. You must `with’ one of them in your application node to activate the corresponding setup.
PolyORB.Setup.No_Tasking_Client: a client node, without any tasking support, configured to use all protocol personalities built with PolyORB. Note that this configuration should not be used with multiple application tasks.
PolyORB.Setup.Thread_Pool_Client: a client node, with tasking enabled, configured to use all protocol personalities built with PolyORB. This configuration places no restriction on the use of tasking by application code. Middleware tasking policy is Thread_Pool.
PolyORB.Setup.Ravenscar_TP_Server: a server node, with tasking enabled, configured to use all protocol personalities built with PolyORB. Middleware tasking runtime follows Ravenscar’s profile restrictions. Middleware tasking policy is Thread_Pool.
PolyORB.Setup.Thread_Per_Request_Server: a server node, with tasking enabled, configured to use all protocol personalities built with PolyORB. Middleware tasking policy is Thread_Per_Request.
PolyORB.Setup.Thread_Per_Session_Server: a server node, with tasking enabled, configured to use all protocol personalities built with PolyORB. Middleware tasking policy is Thread_Per_Session.
PolyORB.Setup.Thread_Pool_Server: a server node, with tasking enabled, configured to use all protocol personalities built with PolyORB. Middleware tasking policy is Thread_Pool.
To use one of these configurations, add a dependency on one of these packages, for example, with PolyORB.Setup.Thread_Pool_Server;. The elaboration of the application (based on Ada rules) and the initialization of the partition (based on the application personalities mechanisms) will properly set up your application.
4.2. Run-time configuration¶
The user may configure some elements of a PolyORB application at run time.
Using the default configurations provided by PolyORB, the parameters are read in the following order: command line, environment variables, configuration file. PolyORB will use the first value that matches the searched parameter.
4.2.1. Using a configuration file¶
A configuration file may be used to configure a PolyORB node. A sample
configuration file may be found in src/polyorb.conf.
The syntax of the configuration file is:
empty lines and lines that have a ‘#’ in column 1 are ignored;
sections can be started by lines of the form [ SECTION-NAME ];
variable assignments can be performed by lines of the form VARIABLE-NAME = VALUE.
Any variable assignment is local to a section.
Assignments that occur before the first section declaration are relative to section [environment]. Section and variable names are case sensitive.
Furthermore, each time a value starts with “file:”, the contents of the file are used instead.
Default search path for polyorb.conf is current
directory. Environment variable POLYORB_CONF may be used to
set up information on configuration file.
PolyORB’s configuration file allows the user to
enable/disable the output of debug information
set up default reference on naming service
select the default protocol personality
set up each protocol personality
The configuration file is read once when running a node, during
initialization. Look in the sample configuration file
src/polyorb.conf to see the available sections and variables.
4.2.2. Using environment variables¶
A variable Var.Iable in section [Sec] can be overridden by setting environment variable “POLYORB_SEC_VAR_IABLE”.
4.2.3. Using the command line¶
PolyORB allows to set up configuration variables on the command line. The syntax is close to the one described in configuration files. A variable Var.Iable in section [Sec] can be overridden with flag –polyorb-<sec>-<var>-<iable>[=<value>].
4.2.4. Using a source file¶
Many embedded systems do not have a filesystem or a shell, so the
previous run-time configuration methods cannot be used on these targets.
On these platforms, a PolyORB node can also be configured using the API of package
PolyORB.Parameters.Static. An example configuration file may be
found in examples/static/po_static_conf.ads.
An array of PolyORB parameters of type Static_Parameters_Array is first declared containing a list of pairs of Variable and Value strings. The syntax is close to the one described in configuration files. A variable Var.Iable in section [Sec] is specified as the pair of strings “[sec]var.iable”, “<value>”.
There is no need to with this po_static_conf.ads in the application
source code, the only requirement is that the array is exported with the
external name “__polyorbconf_optional”. This allows to modify
PolyORB parameters without recompiling the application, just relinking
it. For example:
$ gnatmake -c po_static_conf.ads `polyorb-config`
$ gnatmake -b -l server.adb `polyorb-config` -largs po_static_conf.o
Note the -l flag to gnatmake for linking only, and the need to specify to the linker the object file with the array using -largs if no package withs it.
It should be noticed that this static array of parameters is read at elaboration time only, this API cannot be used to modify the PolyORB configuration at run-time.
4.2.5. Macros¶
If PolyORB is compiled with GNATCOLL support, macros can be used in the configuration file, and will be expanded automatically.
Macros can be defined by setting parameters in the [macros] section of the runtime configuration. The following macros are predefined:
- hostname
The local host name
Macro references can appear anywhere in runtime parameter values and are of the form $*macro-name* or ${*macro-name*}.
For example, in order for a single setting to control all GIOP-based binding modules, one can specify:
[macros]
giop_enable=true
# ... or false
[modules]
binding_data.iiop=${giop_enable}
binding_data.iiop.ssliop=${giop_enable}
binding_data.diop=${giop_enable}
binding_data.uipmc=${giop_enable}
4.3. Setting up protocol personalities¶
PolyORB allows the user to activate some of the available protocol personalities and to set up the preferred protocol. Protocol-specific parameters are defined in their respective sections.
4.3.1. Activating/Deactivating protocol personalities¶
Protocol activation is controlled by PolyORB’s configuration file.
The section [access_points] controls the initialization of access points. An access point is a node entry point that may serve incoming requests.
[access_points]
soap=enable
iiop=enable
diop=disable
uipmc=disable
This example activates SOAP and IIOP, but deactivates DIOP and MIOP.
The section [modules] controls the activation/deactivation of some modules within PolyORB. It is used to enable bindings to remote entities.
[modules]
binding_data.soap=enable
binding_data.iiop=enable
binding_data.diop=disable
binding_data.uipmc=disable
This example enables the creation of bindings to remote objects using SOAP or IIOP. Objects cannot be reached using DIOP or UIPMC.
Note: by default, all configured personalities are activated.
4.3.2. Configuring protocol personality preferences¶
The user may affect a preference to each protocol personality. The protocol with the higher preference will be selected among possible protocols to send a request to a remote node.
See polyorb.binding_data.<protocol>.preference in section [protocol] to set up protocol’s preference.
Possible protocols are defined as the protocols available on the remote node, as advertised in its object reference. IOR or corbaloc references may support multiple protocols; URI references support only one protocol.
Each protocol supports a variety of configuration parameters, please refer to the protocols’ sections for more details.
4.4. Activating debugging traces¶
To activate the output of debug information, you must first configure and compile PolyORB with debugging traces activated (which is the default, unless your build is configured with –enable-debug-policy=ignore).
To output debugging traces on a selected package, create a configuration file with a [log] section and the name of the packages for which you want debug information:
# Sample configuration file, output debug for PolyORB.A_Package
[log]
polyorb.a_package=debug
Note that some packages may not provide such information. See the sample
configuration file src/polyorb.conf for the complete list of
packages that provide traces.
A default logging level may be specified using a line of the form
default=<level>
Time stamps may optionally be prepended to every generated trace. This is enabled using:
timestamp=true
4.5. Tracing exceptions¶
To trace exception propagation in PolyORB’s source code, activate debugging traces for package PolyORB.Exceptions.
4.6. polyorb.gpr¶
This section describes how to build your program using project files. An alternative method, using polyorb-config, is described in the following section. polyorb-config is intended primarily for Unix-like systems. The project-file method will work on all supported systems.
To build your application, create a project file as usual. Import the polyorb.gpr project by putting with “polyorb”; in your project file.
Set the ADA_PROJECT_PATH environment variable to point to the directory containing polyorb.gpr, which is <prefix>/lib/gnat. If SOAP is being used, ADA_PROJECT_PATH must also be set so we can find xmlada.gpr.
If your project file is my_proj.gpr, you can build it by saying:
$ gnatmake -P my_proj
See the GNAT User’s Guide and the GNAT Reference Manual for more information on project files.
4.7. polyorb-config¶
polyorb-config returns path and library information on PolyORB’s installation. It can be used on the gnatmake command line, like this:
$ gnatmake my_program.adb `polyorb-config`
NAME
polyorb-config - script to get information about the installed version
of PolyORB.
SYNOPSIS
polyorb-config [--prefix[=DIR]] [--exec-prefix[=DIR]] [--version|-v]
[--config] [--libs] [--cflags] [--idls] [--help]
DESCRIPTION
polyorb-config is a tool that is used to determine the compiler and
linker flags that should be used to compile and link programs that use
PolyORB.
OPTIONS
polyorb-config accepts the following options:
--prefix[=DIR]
Output the directory in which PolyORB architecture-independent
files are installed, or set this directory to DIR.
--exec-prefix[=DIR]
Output the directory in which PolyORB architecture-dependent
files are installed, or set this directory to DIR.
--version
Print the currently installed version of PolyORB on the stan-
dard output.
--config
Print the configuration of the currently installed version of
PolyORB on the standard output.
--libs Print the linker flags that are necessary to link a PolyORB
program.
--cflags
Print the compiler flags that are necessary to compile a Poly-
ORB program.
--idls
Output flags to set up path to CORBA's IDL for idlac.
--with-appli-perso=P,P,P
Restrict output to only those flags relevant to the listed
applicative personalities.
--with-proto-perso=P,P,P
Restrict output to only those flags relevant to the listed
protocol personalities.
--with-corba-services=S,S,S
Restrict output to only those flags relevant to the listed
services.
--help Print help message.