Chapter 32 Using the Thread Manager

Using the Thread Manager

The Thread Manager is a built-in Jaguar component. You can create a proxy and execute methods the same way that you would call any other component. Each thread executes a run method in a Jaguar component that you specify.

The Thread Manager must be called from a Jaguar component. You may want to create a control component and client application that allows an administrator to start and stop threads.

Before you start

Before running components in the Thread Manager, make sure you understand how the component must be prepared, how threads are run in thread groups, and the effect of a thread group's run interval.

Adapting components to be run by the Thread Manager

Each thread runs a Jaguar component instance. To be run by the Thread Manager, the component must have a run method with this IDL signature:

void run ( );

The Thread Manager calls the run method one or more times, depending on how you configure the run interval (described below).

The Thread Manager is itself a Jaguar component, and runs your component using intercomponent calls. All component properties, including transaction attributes, are in effect when your component is run by the Thread Manager. The Thread Manager executes with the system identity, as does your component's run method.

Understanding thread groups

Threads are associated with a thread group. To start, stop, suspend, or manage the run interval of threads, you must specify the group name. These operations affect all threads in the specified group. The group name is simply a string. Group names have a scope limited to one Jaguar server; that is, you cannot have two like-named groups in the same server. If two applications use the same group name, their Thread Manager calls affect threads in both applications. You can run different components in one thread group.

Naming conventions for thread groups To avoid collisions between thread groups used by different applications, use the reverse-domain naming convention for group names, as used in Java package names. For example, "com.foo.mythreadgroup".

Understanding the run interval

Each thread group has a run interval, which determines how often the Thread Manager calls the run method. The run interval can be:

Run interval	Meaning
A positive integer n	The Thread Manager calls run repeatedly, waiting approximately n seconds after each time the run method returns. The actual time can vary depending on scheduling of calls to other methods and the server's processing load.
0	The Thread Manager calls run repeatedly, with no waiting between invocations.
-1 (the default)	The Thread Manager calls run only once.

To allow threads to be stopped or suspended, you must configure a positive or 0-length run interval and code each component's run method to perform a repetitive task, then return. The run interval has no effect if your run method never returns.

You can use a run interval to schedule periodic tasks, such as refreshing a cached copy of a database query result. You can also tune how much CPU time your component consumes if it performs CPU-intensive tasks such as lengthy calculations; such tuning also requires that you adjust the amount of work done in each invocation of the run method.

You can also use the Message Service to schedule periodic background processing. For example, you can configure a run interval of -1 (so Thread Manager calls run once only) and schedule another component to start threads at the desired interval. See "Subscribing to scheduled messages" for more information.

Instantiating the Thread Manager

Other than restricted access, the Thread Manager can be instantiated as you would instantiate any other component.

Obtaining authorized access

To instantiate the Thread Manager, your component must execute with with the system identity. These are the recommended ways to satisfy this constraint:

Start threads from a service component and create the Thread Manager proxy in the service's start or run method. These methods execute with the system identity.
For a component that is pooled or shared, create the Thread Manager proxy in the component's class constructor, the setSessionContext or setEntityContext method (for EJB components), or the setObjectContext method (for CORBA components). All of these methods execute with the system identity.
For a component that is not a service and not pooled or shared, you must delegate Thread Manager operations to another component that is pooled or shared.

Instantiating a proxy

Use the standard technique for your component model to instantiate the Thread Manager proxy.

CORBA (C++ and Java), ActiveX, and PowerBuilder components must declare a stub for the CtsComponents::ThreadManager IDL interface, then instantiate the component named CtsComponents/ThreadManager.

EJB components must use the home interface com.sybase.ejb.cts.ThreadManagerHome to create a stub for the remote interface com.sybase.ejb.cts.ThreadManager. Look up the name CtsComponents/ThreadManager to obtain the home interface.

Starting threads

To start threads:

Optionally, configure a run interval by calling the setRunInterval method, specifying the group name.
If necessary, create proxies for the components that will run in the thread group. For stateless or shared-instance components, you can use one proxy instance to run the component on multiple threads. For stateful components, create a proxy for each component instance and initialize the instance state as necessary.
Start the desired number of threads by calling the start method once per thread. In each call, specify the group name and pass a proxy for the component that is to run in the thread.

Suspending and resuming execution

To suspend the threads in a group, call the ThreadManager::suspend method, specifying the group name. Each thread is suspended when it next returns from its run method.

To resume execution, call the ThreadManager:resume method.

Stopping execution

You can only stop threads that return from their run method. The Thread Manager stops each thread the next time it returns from its run method.

You can stop threads in two ways:

By decreasing the thread count Call the ThreadManager::setThreadCount method to reduce the number of threads executing in the thread group.
By stopping all threads in the group Call the ThreadManager::stop method to stop all threads in the group. This method is equivalent to calling ThreadManager::setThreadCount to reduce the thread count to zero.