•
|
If the _is_reentrant method returns TRUE, a new thread is allocated from the pool and the request is dispatched to the appropriate method using the same servant instance. It is the responsibility of the servant implementation code to ensure the integrity of the state of the object when multiple threads interact with it.
|
•
|
If the _is_reentrant method returns FALSE, a new instance of the servant is created and the method is dispatched to the new instance. This instance is not automatically deleted. Future reentrant requests may be dispatched to either instance.
|
To override the default implementations of the ServerBase class, an application developer can create a class that derives from
ServerBase. In addition to
ServerBase methods already supported, these methods are provided to support the implementation of multithreaded server applications:
The buildobjserver and
buildobjclient commands include the following thread-management capabilities.
•
|
The buildobjserver command includes platform-specific thread library support so that server applications are compatible with the multithreading support in the Oracle Tuxedo software.
|
The buildobjserver command includes command-line options for building multithreaded or single-threaded server applications.
•
|
The buildobjclient command includes platform-specific thread library support so that client applications can be compatible with the multithreading support provided in the Oracle Tuxedo software.
|
The buildobjserver command supports multithreaded CORBA server applications through the following capabilities:
Server applications generated by the buildobjserver command are compiled using the correct platform-specific compiler settings, and are linked using the correct platform-specific thread support libraries. This ensures compatibility with the shared libraries provided by the Oracle Tuxedo software.
Note:
|
When you specify -t in your build of a CORBA server application, you should set the MAXDISPATCHTHREADS parameter in the UBBCONFIG file to a value greater than 1; otherwise, the CORBA server application will run as a single-threaded server.
|
If you implement your own Server class, inheriting from the
ServerBase class, you must specify your alternate
Server class in the
buildobjserver command using the
-b option. The
buildobjserver command provides the following syntax to support the
-b option:
buildobjserver [-v] [-o outfile] [-f {
firstfiles|@
def-file}]
[-l {
lastfiles|@
def-file}] [-r
rmname] [-b
bootserverclass] [-t]
In the preceding syntax, the value for bootserverclass specifies the C++ class to be used when the CORBA server application is booted. If you do not specify the
-b option, the Oracle Tuxedo system creates an instance of the class named
Server.
When you specify the -b option, the Tuxedo system creates a main function for the alternate server class, and your project must supply a header file with the name you specified for
bootserverclass on the
-b option. The header file contains the definition of the alternate C++ class. This alternate
Server class must inherit from the
ServerBase class.
For example, if the command line specifies -b AslanServer, the application project must supply an
AslanServer.h file. The
AslanServer.h file is an example of a
bootserverclass.h file. A
bootserverclass file provides logic similar to this code sample:
// File name: AslanServer.h
#include <Server.h>
class AslanServer : public ServerBase {
public:
CORBA::Boolean initialize(int argc, char** argv);
void release();
Tobj_Servant create_servant(const char* interfaceName);
Tobj_Servant create_servant_with_id(const char* interfaceName,
const char* stroid);
CORBA::Boolean thread_initialize(int argc, char** argv);
void thread_release();
};
When you use the buildobjclient command to create a client application executable program, the application is compiled using the correct platform-specific compiler settings and linked using the correct thread support libraries for your operating system. This ensures that clients are compatible with the shared libraries provided by the Oracle Tuxedo software.
Use the buildobjserver -t option to inform the Oracle Tuxedo system that the CORBA server application is thread safe. The
-t option indicates that the application does not employ shared context data or other programming constructs that are not thread safe. If you run single-threaded applications that are not thread safe in a multithreaded environment, you risk data corruption.
•
|
Do not assume that the servant’s activate_object or deactivate_object methods are executed in the same thread as the request in which they were originally invoked.
|
Note:
|
The SIGKILL signal to terminate a process is supported. The use of SIGIO is not supported in Oracle Tuxedo CORBA for single or multithreaded applications.
|
The thread-per-request server implementation for SimplePerRequest demonstrates the use of a user-defined server class that implements thread initialization methods. The
SimplePerRequest server process handles each request from a client in a separate thread of control. Each time a new request arrives, a thread is allocated from the thread pool to handle the request. Once the request has been processed and the reply sent, the thread is released back to the pool. This model is useful for servers that handle long-duration requests from multiple clients.
•
|
The to_upper method accepts a string from the client application and converts it to uppercase letters.
|
•
|
The to_lower method accepts a string from the client application and converts it to lowercase letters.
|
•
|
The forward_upper method creates an application-managed thread to another instance of the server and forwards the request received from the client to the new server instance to convert the string to uppercase letters.
|
•
|
The forward_lower method creates another instance of the Simple object and forwards the request received from the client to the new instance to convert the string to lowercase letters.
|
Figure 4‑2 shows the operation of the simpapp_mt sample application, employing both the thread-per-object and thread-per-request threading models.
Listing 4‑2 shows the content of the
simple.idl file, describing the CORBA interface in the simpapp_mt sample application.
The TUXDIR environment variable must be set to the directory path where you installed the Oracle Tuxedo software. For example:
Execute the echo command to show the setting of
TUXDIR:
1.
|
Execute the ksh command at the prompt to launch the Korn shell.
|
2.
|
Execute the printenv command to show the setting of TUXDIR:
|
2.
|
At the ksh prompt, enter the export command to set the value for the TUXDIR environment variable:
|
2.
|
Copy the simpapp_mt files to the working directory.
|
> copy %TUXDIR%\samples\corba\simpapp_mt\* work_directory
2.
|
Copy all simpapp_mt files to the working directory.
|
> cp $TUXDIR/samples/corba/simpapp_mt/* work_directory
Table 4‑1 lists and describes the simpapp_mt files used to build and run the application.
|
|
|
|
|
|
|
Readme file that provides information about building and running the simpapp_mt sample application.
|
|
|
|
|
|
|
|
|
|
Source code that includes implementations for Simple and SimplePerObjectFactory servants that are to be included in a server. The CORBA server is started using a thread-per-object concurrency strategy.
|
|
Source code file for declaring Simple and SimplePerObjectFactory servants to be included in a server.
|
|
|
|
Source code that includes implementations for Simple and SimplePerRequestFactory servants that are to be included in a reentrant server. The reentrant CORBA server is started using a thread-per-request concurrency strategy.
|
|
Source code file for declaring Simple and SimplePerRequestFactory servants to be included in a reentrant server.
|
|
|
|
An example of a bootserverclass.h file, containing the declarations required for the user-defined Server class in the simpapp_mt sample application.
|
|
|
|
|
> chmod u+r work_directory/*.*
The runme command automates the following steps:
6.
|
Creates a setenv.ksh file (UNIX) or setenv.bat file (Windows) so that you can build and run this sample step-by-step.
|
•
|
log—compile, server boot, or server shutdown errors
|
•
|
output—client application output and exceptions
|
•
|
ULOG.date—server application errors and exceptions
|
Table 4‑2 and
Table 4‑3 identify and describe the files created by executing the
runme command.
|
|
|
Created by the idl command for the simple.idl file. This module contains the client stub function for the Simple and SimplePerRequestFactory interface.
|
|
Created by the idl command for the simple.idl file. This module contains definitions and prototypes for the Simple and SimplePerRequestFactory interfaces.
|
|
Created by the idl command for the simple.idl file. This module contains the skeleton functions for the Simple_i and SimplePerRequestFactory_i implementations.
|
|
Created by the idl command for the simple.idl file. This module contains definitions and prototypes for the skeleton classes for the Simple_i and SimplePerRequestFactory_i interfaces.
|
|
Created by the buildobjclient command for the simple_c.cpp and simple_client.cpp files.
|
|
Created by the buildobjserver command for the simple_c.cpp, simple_s.cpp, simple_per_object_i.cpp, simple_per_object_server.cpp, and thread_macros.cpp files.
|
|
Created by the buildobjserver command for the simple_c.cpp, simple_s.cpp, simple_per_request_i.cpp, simple_per_request_server.cpp, and thread_macros.cpp files.
|
|
Created by the runme command to capture the results from running this script.
|
|
Created by the runme command to contain the security encryption key database file.
|
|
|
|
Created by the runme command to store the input that the runme command provides to the C++ client application.
|
|
Created by the runme command to contain the output when the runme command executes the C++ client application.
|
|
Created by the runme command to contain the expected output when the runme command is executed. The output file is compared to determine whether the test passed or failed.
|
|
Created by the runme command to contain the output generated by the runme command. If the command fails, check this file and the ULOG file for errors.
|
|
|
|
|
|
Contains messages generated by tmboot. If the -noredirect server option is specified in the UBBCONFIG file, the fprintf method sends the output to this file.
|
|
Contains messages generated by tmboot. If the -noredirect server option is specified in the UBBCONFIG file, the fprintf method sends the output to this file.
|
|
Generated by the tmboot command in the runme command. It contains filtering and notification rules used by the TMSYSEVT process.
|
|
|
|
UBBCONFIG file for the simpapp_mt sample application.
|
|
ULOG file for storing run-time errors.
|
2.
|
Execute tmboot -y to launch the application. Information similar to the following is displayed:
|
Table 4‑4 describes the server processes started by
tmboot.
|
|
|
|
|
TMFFNAME server processes:
•
|
Master NameManager— TMFFNAME server process started when you specify both the -N option and the -M option.
|
•
|
SLAVE NameManager— TMFFNAME server process started when you specify only the -N option.
|
•
|
FactoryFinder object—a TMFFNAME server process started with the -F option contains this object.
|
|
|
|
|
|
|
|
The MAXDISPATCHTHREADS and
MINDISPATCHTHREADS parameters for specifying the maximum and minimum sizes of the thread pool are in the
SERVERS section of the
UBBCONFIG file. For examples of how to specify these parameters, see
Listing 4‑4. A multithreaded CORBA application uses these values to create and manage the thread pool.
The MAXDISPATCHTHREADS parameter determines the maximum number of concurrently dispatched threads that each server process can spawn. When specifying this parameter, consider the following:
•
|
The value for MAXDISPATCHTHREADS determines the maximum size the thread pool can grow to be, as it increases in size to accommodate incoming requests.
|
•
|
The default value for MAXDISPATCHTHREADS is 1. If you specify a value greater than 1, the system creates and uses a special dispatcher thread. This dispatcher thread is not included in the number of threads determining the maximum size of the thread pool.
|
Note:
|
When you build a multithreaded CORBA server application specifying buildobjserver -t, that server is capable of running in multithreaded mode. To run as a multithreaded CORBA server application, the MAXDISPATCHTHREADS parameter in the UBBCONFIG file must be set to a value greater than 1; if it is not, the server application will run in single-threaded mode.
|
The value of the MAXDISPATCHTHREADS parameter affects other parameters. For example, the
MAXACCESSORS parameter controls the number of simultaneous accesses to the Oracle Tuxedo system, and each thread counts as one accessor. For a multithreaded server application, you must account for the number of system-managed threads that each server is configured to run. A
system-managed
thread is a thread that is started and managed by the Oracle Tuxedo software, as opposed to threads started and managed by an application. Internally, Oracle Tuxedo manages a pool of available system-managed threads. When a client request is received, an available system-managed thread from the thread pool is scheduled to execute the request. When the request is completed, the system-managed thread is returned to the pool of available threads.
Use the MINDISPATCHTHREADS parameter to specify the number of server dispatch threads that are started when the server is initially booted. When you specify this parameter, consider the following:
•
|
The value for MINDISPATCHTHREADS determines the initial allocation of threads in the thread pool.
|
Use the CONCURR_STRATEGY parameter to specify the threading model a multithreaded CORBA server application is to use. The
CONCURR_STRATEGY parameter accepts either of these values:
When you specify CONCURR_STRATEGY = PER_REQUEST to employ the thread-per-request model, each invocation on the CORBA server application is assigned to an arbitrary thread from the threads pool.
When you specify CONCURR_STRATEGY = PER_OBJECT to employ the thread-per-object model, each active object is associated with a single thread at any one time. Each request for an object establishes an association between a dispatch thread and the object.
If the value for MAXDISPATCHTHREADS is greater than one and you do not specify a value for
CONCURR_STRATEGY, the threading model is set to
PER_OBJECT.
Use the MAXOBJECTS parameter to specify the maximum number of objects per machine to be accommodated in the Active Object Map tables in the bulletin board. You can set this value in either the
RESOURCES section or the
MACHINES section of the configuration file. The
MAXOBJECTS number in the
RESOURCES section is a system-wide setting. Use the
MAXOBJECTS number in the
MACHINES section to override the system-wide setting on a per-machine basis.
The value for number is limited only by the resources of your operating system.
Listing 4‑4 shows a the
UBBCONFIG file for the Oracle Tuxedo Threads sample application. The threads-related parameters are presented in
boldface text.
Note:
|
The value for the MAXOBJECTS parameter affects the operation of a multithreaded server. However, this parameter is not specific to multithreaded servers, since it also affects the operation of single-threaded servers. Increasing the value for MAXOBJECTS results in the consumption of additional system resources for any server.
|
*RESOURCES
IPCKEY 55432
DOMAINID simpapp
MAXOBJECTS 100
MASTER SITE1
MODEL SHM
LDBAL N
*MACHINES
"sunstar"
LMID = SITE1
APPDIR = "/rusers1/lyon/samples/corba/simpapp_mt"
TUXCONFIG = "/rusers1/lyon/samples/corba/simpapp_mt/results/tuxconfig"
TUXDIR = "/usr/local/TUXDIR"
MAXWSCLIENTS = 10
MAXACCESSERS = 200
*SERVERS
DEFAULT:
RESTART = Y
MAXGEN = 5
TMSYSEVT
SRVGRP = SYS_GRP
SRVID = 1
TMFFNAME
SRVGRP = SYS_GRP
SRVID = 2
CLOPT = "-A -- -N -M"
TMFFNAME
SRVGRP = SYS_GRP
SRVID = 3
CLOPT = "-A -- -N"
TMFFNAME
SRVGRP = SYS_GRP
SRVID = 4
CLOPT = "-A -- -F"
simple_per_object_server
SRVGRP = APP_GRP1
SRVID = 1
MINDISPATCHTHREADS = 10
MAXDISPATCHTHREADS = 100
CONCURR_STRATEGY = PER_OBJECT
RESTART = N
simple_per_request_server
SRVGRP = APP_GRP2
SRVID = 2
MINDISPATCHTHREADS = 10
MAXDISPATCHTHREADS = 100
CONCURR_STRATEGY = PER_REQUEST
RESTART = N
ISL
SRVGRP = SYS_GRP
SRVID = 5
CLOPT = "-A -- -n //sunbstar:2468 -d /dev/tcp"