5
Using 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:

• Concepts

• Multithreaded Agent Architecture

• Multithreaded Agent Administration

  Note: Even though Heterogeneous Services supports multithreaded agents, this functionality is not necessarily available in all Heterogeneous Services based gateways. Not only must multithreaded agents have generic support, which Heterogeneous Services provides, but support for multithreaded agents must also be added to the driver.

Concepts

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 per user-session and per 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 also 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 an disproportionate amount of system resources without any discernible benefit.

The Advantage of Multithreading

Usually, only a small percentage of these agent processes are actually active at a given moment. This makes it possible to more efficiently use system resources by using the multithreaded agent feature of Oracle Transparent Gateways. The multithreaded agent uses a pool of shared agent processes. (The number of these shared agent processes is usually considerably less than the number of user sessions.) The tasks requested by the user sessions are put on a queue and are picked up by the first available multithreaded agent.

Note Also: For more information about multithreading, see the following: Oracle9i Database Administrator's Guide Oracle9i SQL Reference Oracle9i Net Services Administrator's Guide Oracle9i Net Services Reference Guide

Multithreaded Agent Architecture

This section describes the architecture of multithreaded agents.

This section contains the following topics:

• Overview

• The Monitor Thread

• Dispatcher Threads

• Task Threads

Overview

In the architecture for multithreaded agents, there are three kinds of threads:

• A single monitor thread

• Several dispatcher threads

• Several task threads.

Typically there are many more task threads than dispatcher threads. The architecture is shown in Figure 5-1.

Figure 5-1 Multithreaded Agent Architecture

Text description of the illustration multitha.gif

Each request issued by a user session is represented in Figure 5-1 by a separate type of arrow.

Each request is processed by means of the three different kinds of threads

• 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

• The dispatcher threads are responsible for the following:
  • Handling communication with the Oracle server

  • Passing task requests onto the task threads

• The task threads handle requests from the Oracle processes

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

Note: 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.

Multi-threaded agents are started on a per system-identifier(SID) basis. Each TNS listener that is running on a system listens for incoming connection requests for a set of SIDs. To connect to a process by means of a listener, the SID in the SQL*Net connect string should be one of the SIDs that the listener is listening for. For each SID, a separate agent process is started and incoming connections for that SID are handed over by the listener to that process.

The agent process is pre-started. A separate agent control utility stops and starts the multithreaded agent itself.

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

The Monitor Thread

The monitor thread is the first thread to be started with an multithreaded agent process. The monitor thread does the following:

• Creates the dispatcher and task threads

• 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.

• Monitors the other threads and send load information about the dispatcher threads to all the listener processes handling connections to this agent
  • This way, the listeners can hand over incoming connections to the least loaded dispatcher.

• Monitors each of the threads it has created

Dispatcher Threads

Dispatcher threads do the following:

• Accept incoming connections and task requests from Oracle 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: 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 do the following:

• Pick up requests from a queue

• Perform the necessary operations.

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

Multithreaded Agent Administration

This section explains how you can administer multithreaded agents.

This section contains the following topics.

• Overview

• Single Command Mode Commands

• Shell Mode Commands

Overview

The multithreaded agent is started and stopped by an agent control utility called agtctl, which works much like lsnrctl. The main differences are that lsnrctl reads a configuration file whereas aftctl takes information form the command line and writes it to a control file. There is no equivalent for listener.ora as far as agtctl is concerned.

You can run agtctl in one of two ways:

1. Commands can be run from the UNIX (or DOS) shell

   This mode is called single command mode

2. You can type 'agtct' and you will get an AGTCTL> prompt and you can type commands from within the agtctl shell.

   This mode is called shell mode

Single Command Mode Commands

The commands (in single command mode are) are as follows:

1. Startup

   agtctl startup agent_name agent_sid
   
   

2. Shutdown

There are three variants of the shutdown command

1. agtctl shutdown <sid>

2. agtctl shutdown immediate <sid>

3. agtctl shutdown abort <sid>

If you issue the first variant, agtctl will talk to the agent and ask it to terminate itself gracefully. In other words, all sessions will complete the operations they are currently doing and then shutdown.

If you issue the second variant, agtctl will talk to the agent and tell it terminate immediately. In other words, the agent process will exit immediately regardless of the state of current sessions.

If you issue the third variant, agtctl will not talk to the agent at all. It will just issue a system call to kill the agent process.

3. Setting parameters

   agtctl set parameter_value agent_sid
   
   

4. Unsetting parameters

   agtctl unset parameter agent_sid
   

5. Examining parameter values

   agtctl show parameter agent_sid
   

6. Deleting all settings for a particular agent system identifier

   agtctl delete agent_sid
   

Shell Mode Commands

In shell mode, you can start agtctl by typing 'agtctl' whereupon you will get an 'AGTCTL>' prompt.

First, 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.

The commands are all the same as those for the single command mode commands with the exception that you can drop the 'agtctl' and agent_sid.

To set an initialization parameter value, type:

set parameter value

Use the following table to set your initialization parameters.

Table 5-1 Initialization Parameters for agtctl

parameter	description
max_dispatchers	(maximum number of dispatchers)
tcp_dispatcher	(number of dispatchers listening on tcp - the rest are using ipc).
max_task_threads	(number of task threads)
listener_address	(address on which the listener is listening - needed for registration)
shutdown_address	(address on which the agent should listen for shutdown messages from agtctl)
language	(language name)