5 Multithreaded Agents

This chapter explains what multithreaded agents are, how they contribute to the overall efficiency of a distributed database system, and how to administer multithreaded agents.

This chapter contains the following sections:

5.1 Why Use Multithreaded Agents?

This section explains how multithreaded agents contribute to the efficiency of Heterogeneous Services and Oracle Transparent Gateways.

This section contains the following topics:

5.1.1 The Challenge of Dedicated Agent Architecture

By default, a Heterogeneous Services agent is started for each user session. When a user session attempts to access a non-Oracle system through a database link, an agent process is started that is dedicated to that user session and that database link. The agent process terminates only when the user session ends or when the database link is closed. Separate agent processes are started under the following conditions:

  • The same user session uses two different database links to connect to the same non-Oracle system

  • Two different user sessions use the same database link to access the same non-Oracle system

This architecture may consume an unnecessarily large amount of system resources. For example, suppose that there are several thousand user sessions simultaneously accessing the same non-Oracle system. Because an agent process is started for each session, there are several thousand agent processes running concurrently. The agent processes operate regardless of whether each individual agent process is actually active at the moment. Thus agent processes and open connections can consume a disproportionate amount of system resources. When sessions connect to the Oracle database server, 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.

5.1.2 The Advantage of Multithreading

The Oracle shared server architecture assumes that even when there are several thousand user sessions currently 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 tasks requested 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.

Multithreaded Heterogeneous Services agents provide similar functionality for connections to non-Oracle systems. The multithreaded 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 agent thread. Because only a small percentage of user connections are active at a given moment, using a multithreaded architecture allows for more efficient use of system resources.

5.2 Multithreaded Agent Architecture

One multithreaded agent must be started for each system identifier (SID) before any attempt is made to connect to the non-Oracle system. This is done using the agent control utility agtctl. This utility is also used to configure the agent and to shut down the agent.

Each Oracle Net listener that is running on a system listens for incoming connection requests for a set of SIDs. If the SID in an incoming Oracle Net connect string is one of the SIDs that the listener is listening for, then that listener processes the connection. Further, if a multithreaded agent has been started for the SID, then the listener passes the request to that agent.

In the architecture for multithreaded agents, each incoming connection request is processed by different kinds of threads:

  • A single monitor thread. The monitor thread is responsible for the following:

    • Maintaining communication with the listener

    • Monitoring the load on the process

    • Starting and stopping threads when required

  • Several dispatcher threads. The dispatcher threads are responsible for the following:

    • Handling communication with the Oracle server

    • Passing task requests to the task threads

  • Several task threads. The task threads handle requests from the Oracle processes.

The multithreaded agent architecture is illustrated in Figure 5-1. Each request issued by a user session is represented by a separate type of arrow. There is no representation of the monitor thread in this illustration, because the monitor thread is created once when the multithreaded agent is started, and it creates and monitors the other threads. There are usually many more task threads than dispatcher threads.

Figure 5-1 Multithreaded Agent Architecture

Description of heter011.gif follows
Description of the illustration heter011.gif

These three thread types roughly correspond to the Oracle multithreaded server PMON, dispatcher, and shared server processes, respectively.


All requests from a user session go through the same dispatcher thread, but can be serviced by different task threads. It is also possible for several task threads to use the same connection to the non-Oracle system.

Each type of thread is discussed in more detail in the following sections:

5.2.1 Monitor Thread

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

  • It creates the dispatcher and task threads.

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

  • It monitors the other threads and sends load information about the dispatcher threads to all the listener processes handling connections to this agent. This enables the listeners to hand over incoming connections to the least loaded dispatcher.

  • It continues to monitors each of the threads it has created.

5.2.2 Dispatcher Threads

Dispatcher threads perform the following functions:

  • They accept incoming connections and task requests from Oracle servers.

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

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


    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.

5.2.3 Task Threads

Task threads perform the following functions:

  • They pick up requests from a queue.

  • They perform the necessary operations.

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

5.3 Administering Multithreaded Agents

One multithreaded Heterogeneous Services agent must be started for each system identifier (SID) before any attempt is made to connect to the non-Oracle system. Any agent not started in this fashion will not function in multithreaded mode and must be set up as described in Section 4.1, "Setting Up Access to Non-Oracle Systems".

A multithreaded agent is started, stopped, and configured by an agent control utility called agtctl, which works like lsnrctl. However, unlike lsnrctl, which reads a configuration file (listener.ora), agtctl takes configuration information from the command line and writes it to a control file.

The following topics are discussed in this section:

5.3.1 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 5-1.

Table 5-1 Agent Control Utility Commands

Command Description
startup Starts a multithreaded agent
shutdown Stops a multithreaded agent
set Sets a configuration parameter for a multithreaded agent
unset Causes a parameter to revert to its default value
show Displays the value of a configuration parameter
delete Deletes the entry for a particular SID from the control file
exit Exits shell mode
help Lists available commands

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.


  • All commands are case-sensitive.

  • The agent control utility puts its control file in either the directory pointed to by the AGTCTL_ADMIN environment variable or in the directory pointed to by the TNS_ADMIN environment variable. Ensure that at least one of these environment variables is set and that it points to a directory to which the agent has access.

  • If the Heterogeneous Services agent requires an environment variable to be set, or if the ENVS parameter was used when configuring the listener.ora entry for the agent working in dedicated mode, then all required environment variables must be set in the UNIX or DOS shell that runs the agtctl utility.

5.3.2 Using agtctl in Single-Line Command Mode

This section describes the use of agtctl commands. They are presented in single-line command mode. Setting Configuration Parameters for a Multithreaded Agent

Set the configuration parameters for a multithreaded agent before you start the agent. If a configuration parameter is not specifically set, a default value is used. Configuration parameters and their default values are shown in Table 5-2.

Use the set command to set multithreaded agent configuration parameters.


agtctl set  parameter  parameter_value  agent_sid

parameter is the parameter that you are setting.
parameter_value is the value being assigned to that parameter.
agent_sid is the SID that this agent will service. This must be specified for single-line command mode.


agtctl  set  max_dispatchers 5 salesDB Starting a Multithreaded Agent

Use the startup command to start an agent in multithreaded mode.


agtctl startup  agent_name  agent_sid

agent_name is the name of the agent executable. For example, extproc is an agent name.
agent_sid is the SID that this agent will service. This must be specified for single-line command mode.


agtctl startup  extproc  salesDB Shutting Down a Multithreaded Agent

Use the shutdown command to stop a multithreaded agent. There are three forms of shutdown:

  • Normal

    Normal shutdown is the default. It causes agtctl to talk to the agent and ask it to terminate itself gracefully. All sessions complete the operations they are currently doing and then shut down.

  • Immediate

    For an Immediate shutdown, agtctl talks to the agent and tells it to terminate immediately. The agent process exits immediately regardless of the state of current sessions.

  • Abort

    For an Abort shutdown, agtctl does not talk to the agent at all. It issues a system call to kill the agent process.


agtctl shutdown [immediate|abort] agent_sid

agent_sid is the SID that the agent services. It must be specified for single-line command mode.


agtctl shutdown immediate salesDB Examining the Value of Configuration Parameters

To examine the value of a configuration parameter, use the show command.


agtctl  show  parameter agent_sid

parameter is the parameter that you are examining.
agent_sid is the SID that this agent will service. This must be specified for single-line command mode.


agtctl  show  max_dispatchers salesDB Resetting a Configuration Parameter to Its Default Value

You can reset a configuration parameter to its default value using the unset command.


agtctl  unset  parameter agent_sid

parameter is the parameter that you are modifying (or unsetting).
agent_sid is the SID that this agent services. It must be specified for single-line command mode.


agtctl  unset  max_dispatchers salesDB Deleting an Entry for a Specific SID from the Control File

The delete command deletes the entry for the specified SID from the control file.


agtctl  delete  agent_sid

agent_sid is the SID entry to delete.


agtctl  delete  salesDB Requesting Help

Use the help command to view a list of available commands for agtctl or to see the syntax for a particular command.


agtctl help [command]

command is the name of the command whose syntax you want to view.


agtctl help set

5.3.3 Using Shell Mode Commands

In shell mode, start agtctl by entering the following:


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

Set the name of the agent SID by entering the following:

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 are examples of shell mode commands. Example: Setting a Configuration Parameter

This example sets a new value for the shutdown_address configuration parameter.

AGTCTL> set shutdown_address (address=(protocol=ipc)(key=oraDBsalesDB)) Example: Starting a Multithreaded Agent

This example starts a multithreaded agent.

AGTCTL> startup extproc

5.3.4 Configuration Parameters for Multithreaded Agent Control

Table 5-2 lists the configuration parameters for the agent control utility.

Table 5-2 Initialization Parameters for agtctl

Parameter Description Default Value
max_dispatchers Maximum number of dispatchers 1
tcp_dispatchers Number of dispatchers listening on tcp (the rest are using ipc) 0
max_task_threads Number of task threads 2
max_sessions Maximum number of sessions 5
listener_address Address on which the listener is listening (needed for registration)
Note: listener_sid is the IPC key to where the listener is listening of the Oracle database.
shutdown_address Address the agent uses to communicate with the listener. This is the address on which the agent listens for all communication, including shutdown messages from agtctl
    (KEY=listener_sid || agent_sid))
  • agent_sid is the SID of the multithreaded agent.

  • || indicates that listener_sid and agent_sid are concatenated into one string.