A Multithreaded extproc Agent

The Challenge of Dedicated Agent Architecture

By default, an extproc agent is started for each user session and the extproc agent process terminates only when the user session ends.

This architecture can consume an unnecessarily large amount of system resources. For example, suppose that several thousand user sessions simultaneously spawn extproc agent processes. Because an extproc agent process is started for each session, several thousand extproc agent processes run concurrently. The extproc agent processes operate regardless of whether each individual extproc agent process is active at the moment. Thus extproc agent processes and open connections can consume a disproportionate amount of system resources. When sessions connect to Oracle Database, this problem is addressed by starting the server in shared server mode. Shared server mode allows database connections to be shared by a small number of server processes.

The Advantage of Multithreading

The Oracle Database shared server architecture assumes that even when several thousand user sessions are open, only a small percentage of these connections are active at any given time. In shared server mode, there is a pool of shared server processes. User sessions connect to dispatcher processes that place the requested tasks in a queue. The tasks are picked up by the first available shared server processes. The number of shared server processes is usually less that the number of user sessions.

The multithreaded extproc agent provides similar functionality for connections to external procedures. The multithreaded extproc agent architecture uses a pool of shared agent threads. The tasks requested by the user sessions are put in a queue and are picked up by the first available multithreaded extproc agent thread. Because only a small percentage of user connections are active at a given moment, using a multithreaded extproc architecture allows more efficient use of system resources.

Monitor Thread

When the agent control utility agtctl starts a multithreaded extproc agent for a SID, agtctl creates the monitor thread. The monitor thread performs these functions:

• Creates the dispatcher and task threads.

• Registers the dispatcher threads with all the listeners that are handling connections to this extproc agent. While the dispatcher for this SID is running, the listener does not start a process when it gets an incoming connection. Instead, the listener gives the connection to this same dispatcher.

• Monitors the other threads and sends load information about the dispatcher threads to all the listener processes handling connections to this extproc agent, enabling listeners to give incoming connections to the least loaded dispatcher.

• Continues to monitor each of the threads it has created.

Dispatcher Threads

Dispatcher threads perform these functions:

• Accept incoming connections and task requests from Oracle Database servers.

• Place incoming requests on a queue for a task thread to pick up.

• Send results of a request back to the server that issued the request.

  Note:

  After a user session establishes a connection with a dispatcher, all requests from that user session go to the same dispatcher until the end of the user session.

Task Threads

Task threads perform these functions:

• Pick up requests from a queue.

• Perform the necessary operations.

• Place the results on a queue for a dispatcher to pick up.

Agent Control Utility (agtctl) Commands

You can start and stop agtctl and create and maintain its control file by using the commands shown in Table A-1.

These commands can be issued in one of two ways:

• You can issue commands from the UNIX or DOS shell. This mode is called single-line command mode.

• You can enter agtctl and an AGTCTL> prompt appears. You then can enter commands from within the agtctl shell. This mode is called shell mode.

The syntax and parameters for agtctl commands depend on the mode in which they are issued.

Using agtctl in Single-Line Command Mode

This section describes the use of agtctl commands. They are presented in single-line command mode.

agtctl set parameter parameter_value agent_sid

agtctl set max_dispatchers 5 salesDB

agtctl startup extproc agent_sid

agtctl startup extproc salesDB

agtctl shutdown [immediate|abort] agent_sid

agtctl shutdown immediate salesDB

agtctl show parameter agent_sid

agtctl show max_dispatchers salesDB

agtctl unset parameter agent_sid

agtctl unset max_dispatchers salesDB

agtctl delete agent_sid

agtctl delete salesDB

agtctl help [command]

agtctl help set

Using Shell Mode Commands

In shell mode, start agtctl by entering:

agtctl

This results in the prompt AGTCTL>. Thereafter, because you are issuing commands from within the agtctl shell, you need not prefix the command string with agtctl.

Set the name of the agent SID by entering:

AGTCTL> set agent_sid agent_sid

All subsequent commands are assumed to be for the specified SID until the agent_sid value is changed. Unlike single-line command mode, you do not specify agent_sid in the command string.

You can set the language for error messages as follows:

AGTCTL> set language language

The commands themselves are the same as those for the single-line command mode. To exit shell mode, enter exit.

The following examples use shell mode commands.

AGTCTL> set shutdown_address (address=(protocol=ipc)(key=oraDBsalesDB))

AGTCTL> startup extproc

Configuration Parameters for Multithreaded extproc Agent Control

Table A-2 describes and gives the defaults of the configuration parameters for the agent control utility.

(ADDRESS_LIST=
    (ADDRESS=
        (PROTOCOL=IPC)
        (KEY=PNPKEY))
    (ADDRESS=
        (PROTOCOL=IPC)
        (KEY=listener_sid))
    (ADDRESS=
        (PROTOCOL=TCP)
        (HOST=127.0.0.1)
        (PORT=1521)))

(ADDRESS=
    (PROTOCOL=IPC)
    (KEY=listener_sid || agent_sid))
(ADDRESS=
    (PROTOCOL=TCP)
    (HOST=127.0.0.1)
    (PORT=1521))

max_dispatchers, tcp_dispatchers, max_task_threads, and max_sessions

To improve performance, you might need to change the values of some or all of the parameters max_dispatchers, tcp_dispatchers, max_task_threads, and max_sessions.

You can calculate the optimum values of max_dispatchers, tcp_dispatchers, max_task_threads with these formulas:

max_dispatchers = CEIL(x/y)
tcp_dispatchers = CEIL(x_tcpip/y)
max_task_threads = CEIL(x/max_sessions)

Where:

• CEIL is a SQL function that returns the smallest integer greater than or equal to its argument.

• x is the maximum number of sessions that can be connected to extproc concurrently.

• y is the maximum number of connections that the system can support for each dispatcher.

• x_tcpip is the maximum number of sessions that can be connected to extproc concurrently by TCP/IP.

  (x - x_tcpip is the maximum number of sessions that can be connected to extproc concurrently by IPC.)

There is no formula for computing the optimum value of max_sessions, which affects max_task_threads.

You must fine-tune these parameter settings, based on the capability of your hardware, and ensure that the concurrent threads do not exhaust your operating system.

The value of max_dispatchers must be at least 1 (which is the default).

Example

Suppose:

• The maximum number of sessions that can be connected to extproc concurrently (x) is 650.

• The maximum number of sessions that can be connected to extproc concurrently by TCP/IP (x_tcpip) is 400.

  (The maximum number of sessions that can be connected to extproc concurrently by IPC is 650-400=250.)

• The maximum number of connections that the system can support for each dispatcher (y) is 100.

• The maximum number of sessions for each task thread (max_sessions) is 20.

The optimum values for these parameters are:

max_dispatchers = CEIL(650/100) = CEIL(6.5)  = 7
tcp_dispatchers  = CEIL(400/100) = CEIL(4)    = 4
max_task_threads = CEIL(650/20)  = CEIL(32.5) = 33

That is, optimally:

• The maximum number of dispatchers is seven.

• Four of the seven dispatchers are listening on TCP/IP, and the remaining three are listening on IPC.

• The maximum number of task threads is 33.

listener_address and shutdown_address

The values of the configuration parameters listener_address and shutdown_address are specified with ADDRESS, as shown in both Table A-2 and Example A-1. Within ADDRESS, you can specify the parameter HOST, which can be either an IPv6 or IPv4 address or a host name. If HOST is a host name, then these values of the optional ADDRESS parameter IP are relevant:

For example, this value of listener_address or shutdown_address restricts it to IPv6 interfaces:

"(ADDRESS=(PROTOCOL=tcp)(HOST=sales)(PORT=1521)(IP=V6_ONLY))"