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 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.
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.
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.
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”.
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.
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.
Other than restricted access, the Thread Manager can be instantiated as you would instantiate any other component.
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:
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:
Delegate Thread Manager operations to another component that is pooled or shared, or
Run the component with an identity that is in the ThreadManager role.
For a base client, connect to EAServer with a user name that is a member of the ThreadManager role.
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.
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.
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.
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.
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. This technique is useful when you want to throttle the execution of the task. For example, during a Web site’s peak usage hours, you can reduce the thread count for background processing to give user threads more CPU time. During off hours, you can reset the thread count and start new threads to raise the thread count again.
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.
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. |
|
|