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:

• Why Use Multithreaded Agents?
• Multithreaded Agent Architecture
• Administering Multithreaded Agents

  Note: Heterogeneous Services supports multithreaded agents, however this functionality may not be available in all Heterogeneous Services based gateways. In addition to the generic support for multithreaded agents that Heterogeneous Services provides, multithreaded agents support must be added to the driver.

Why Use Multithreaded Agents?

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

This section contains the following topics:

• The Challenge of Dedicated Agent Architecture
• The Advantage of Multithreading

The Challenge of Dedicated Agent Architecture

In the architecture of past releases of Heterogeneous Service, agents are started up on a one for each user session basis and one for each database link basis. When a user session attempts to access a non-Oracle system by means of a particular database link, an agent process is started up that is exclusively 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 is simple and straightforward. However, it has the disadvantage of potentially consuming 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 up for each one of them, there are several thousand agent processes running concurrently as well as several thousand connections open to these agent processes. The agent processes are all running regardless of whether each individual agent process is actually active at the moment or not. Because of this, agent processes and open connections can consume a disproportionate amount of system resources without any discernible benefit.

In the case of connections 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.

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 will be 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 by the user sessions on a queue. The tasks are picked up by the first available shared server processes. The number of shared server processes is usually considerably 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 on a queue and are picked up by the first available multithreaded agent thread. Because only a small percentage of user connections are actually active at a given moment, using a multithreaded architecture allows for more efficient use of system resources.

Multithreaded Agent Architecture

Multithreaded agents must be prestarted on a one for each system identifier (SID) basis. 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 TNS 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 will process the connection. Further, if a multithreaded agent has been started for the SID, then the listener will pass the request to that agent.

In the architecture for multithreaded agents, each incoming connection request is processed by means of the three 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 on 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 where each request issued by a user session is represented in by a separate type of arrow. There is no representation of the monitor thread in this illustration, because that thread is created once when the multithreaded agent is started and it creates and monitors the other threads. Typically there are many more task threads than dispatcher threads.

Figure 5-1 Multithreaded Agent Architecture

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

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

• The Monitor Thread
• Dispatcher Threads
• Task Threads

  See Also: Administering Multithreaded Agents for more information on how to start and stop multithreaded agents using the agent control utility

The Monitor Thread

When a multithreaded agent is started for a SID by the agent control utility, the monitor thread is created. The monitor thread performs the following functions:

• It creates the dispatcher and task threads
• It registers the dispatcher threads it has created 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.

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.

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

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

Administering Multithreaded Agents

As discussed earlier, multithreaded Heterogeneous Services agents must be prestarted on a one for each system identifier (SID) basis before any attempt is made to connect to the non-Oracle system. Any agent not spawned in this fashion will not function in multithreaded mode, and must be set up as described in "Setting Up Access to Non-Oracle Systems".

A multithreaded agent is started, stopped, and configured by an agent control utility called agtctl, which works much 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:

• Agent Control Utility (agtctl) Commands
• Using Single-Line Command Mode
• Using Shell Mode Commands
• Configuration Parameters for Multithreaded Agent Control

Agent Control Utility (agtctl) Commands

You start and stop agtctl, and create and maintain its control file, using the commands shown in Table 5-1.

Table 5-1 Agent Control Utility 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 type agtctl and a "AGTCTL>" prompt appears. You then can type commands from within the agtctl shell.

  This mode is called shell mode

The syntax and parameters for agtctl commands vary depending upon the mode in which they are issued.

Using 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

You should set the configuration parameters for a multithreaded agent before you start the agent. They determine how the agent will be configured. 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.

Syntax

agtctl set  parameter  parameter_value  agent_sid

Where:

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

Example

agtctl  set  max_dispatchers 5 salesDB

Starting a Multithreaded Agent

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

Syntax

agtctl startup  agent_name  agent_sid

Where:

• agent_name is the name of the agent. E.g., tg4sybs, tg4msql, hsodbc, or other agent.
• agent_sid is the SID which this agent will service. Must be specified for single-line command mode.

Example

agtctl startup  tg4sybs  salesDB

Shutting Down a Multithreaded Agent

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

• Normal

  This form of shutdown is the default. It causes agtctl will talk to the agent and ask it to terminate itself gracefully. All sessions complete the operations they are currently doing and then shutdown.

• Immediate

  In this form of 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

  In this form of shutdown, agtctl does not talk to the agent at all. It just issues a system call to kill the agent process.

Syntax

agtctl shutdown [immediate|abort] agent_sid

Where:

• agent_sid is the SID which this agent will service. Must be specified for single-line command mode.

Example

agtctl shutdown immediate salesDB

Examining the Value of Configuration Parameters

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

Syntax

agtctl  show  parameter agent_sid

Where:

• parameter is the parameter that you are examining.

Example

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.

Syntax

agtctl  unset  parameter agent_sid

Where:

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

Example

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.

Syntax

agtctl  delete  agent_sid

Where:

• agent_sid is the SID entry to delete.

Example

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.

Syntax

agtctl help [command]

Where:

• command is the command whose syntax you want to view.

Example

agtctl help set

Using Shell Mode Commands

In shell mode, you start agtctl by typing agtctl whereupon you will see an "AGTCTL>" prompt. Thereafter, since you are issuing commands from within the agtctl shell, you do not prefix the command string with the word agtctl.

Next, set the name of the agent SID that you are working with by typing

set  agent_sid  agent_sid

All commands issued after this are assumed to be for this particular 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 optionally set the language for error messages, to other than English, as follows:

set  language  language

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

The following are some examples of shell mode commands.

Example: Setting a Configuration Parameter

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

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

Example: Starting a Multithreaded Agent

This example starts a multithreaded agent.

startup tg4sybs

Configuration Parameters for Multithreaded Agent Control

The following table lists the configuration parameters for the agent control utility.

Table 5-2 Initialization Parameters for agtctl

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

(ADDRESS=
    (PROTOCOL=IPC)
    (KEY=oracle_sid||agent_sid))