About the Thread Manager  Chapter 33: Creating Service Components

Chapter 32: Using the Thread Manager

Using the Thread Manager

The Thread Manager is a built-in EAServer 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 an EAServer component that you specify.

The thread manager is designed primarily for use in server-side code. However, it is possible to call thread manager methods from base clients or Web applications. For example, you can create an administrative client that stops threads created by your application.


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 an EAServer 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).

For EJB components, the run method must be in a remote interface or an additional interface that is neither an EJB remote or local interface. To add such an interface, follow the procedure “Adding interfaces”. You can use the predefined CtsComponents::ThreadBase. Regenerate the component skeleton after adding interfaces.

The Thread Manager is itself an EAServer 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 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.

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

If the run interval is positive or 0, you can change the run interval after threads have been started in the group, the change takes for each thread when it returns from the run method. You cannot change the interval to -1, and changing the interval does not affect threads started with the interval set to -1. In these cases, calling setRunInterval has no effect.

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.


Understanding the thread count

Each thread group has a thread count, which determines how many threads can run simultaneously. The count can be:

Run interval

Meaning

-1 (the default)

There is no limit.

A positive integer n

n threads can execute.

0

No threads can execute..

To change the thread count, call the ThreadManager::setThreadCount method. The change takes effect after threads return from the run method. Thread counts are useful if threads run repeatedly (run interval is positive or 0). For example, if 6 threads are running, and you change the count to 5, the next thread that returns from its run method will not be restarted. The thread count provides a means to throttle the number of running threads, without stopping or suspending all threads.


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 client or component must execute with with the system identity or an identity that is in the ThreadManager role. These are the recommended ways to satisfy this constraint:


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:

  1. Optionally, configure a run interval by calling the setRunInterval method, specifying the group name.

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

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

If you have set a thread count, and try to start more threads than the thread count, the behavior depends on the run interval. If the run interval is -1, all threads are started and run once. If the run interval is 0 or positive, the start method does not create additional threads after the count is reached.


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 threads

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:

If you stop all threads by calling ThreadManager::stop or setting the thread count to 0, you must reset the thread count to a positive value or -1 (meaning infinity) before starting more threads.





Copyright © 2005. Sybase Inc. All rights reserved. Chapter 33: Creating Service Components