Providing support for instance pooling
Benefits of instance pooling
Jaguar components can optionally support instance pooling. Instance
pooling allows Jaguar clients to reuse component instances.
By eliminating the resource drain caused by repeated allocation
of component instances, instance pooling and improves the overall
performance of a Jaguar server.
Specifying pooling options in the wizards
When you create a Jaguar component using one of the PowerBuilder
wizards, you have the option to specify one of the following pooling
options for the component:
| Pooling option | Description |
|---|---|
| Supported | The component is always pooled after each client use. When this option is selected, the CanBePooled event is not triggered for the componentThis option has the effect of setting the component’s pooling property to True. If the Automatic Demarcation/Deactivation setting for the component is enabled, instances are pooled after each method invocation. If the Automatic Demarcation/Deactivation setting is disabled, instances are pooled when the component calls the SetComplete (or SetAbort) method of the TransactionServer context object |
| Not supported | By default, the component is not pooled after each client use. However, you can override the default behavior by scripting the CanBePooled event. In the CanBePooled event, you can specify programmatically whether a particular component instance should be pooled. If you script the CanBePooled event, this event is triggered after each client useThis option has the effect of setting the component’s pooling property to False |
Controlling the state of a pooled instance
When you create a Jaguar component that supports instance
pooling, that component may need to reset its state after each client
has finished using the pooled instance.
To allow you to control the state of a component, Jaguar triggers
one or more of the following events during the lifecycle of the
component:
| Event | PBM code |
|---|---|
| Activate | PBM_COMPONENT_ACTIVATE |
| CanBePooled | PBM_COMPONENT_CANBEPOOLED |
| Deactivate | PBM_COMPONENT_DEACTIVATE |
When the component’s pooling option is set to Supported
(the pooling property is set to True), you may need to script the
Activate and Deactivate events to reset the state of the pooled
component. This is necessary if the component maintains state in
an instance, shared, or global variable.
When the component’s pooling option is set to Not
Supported (the pooling property is set to False), you can optionally
script the CanBePooled event to specify whether a particular component
instance should be pooled. If you script the CanBePooled event,
you may also need to script the Activate and Deactivate events to
reset the state of the pooled component. If you do not script the
CanBePooled event, the component instance is not pooled.
The Jaguar Component Start and Object wizards automatically
include the Activate and Deactivate events to a custom class user
object that will be deployed as a Jaguar component. If you want
to script the CanBePooled event, you need this event by hand. If
you do this, you need to be sure to map the event to the correct
PBM code.
Constructor and Destructor are fired once When instance pooling is in effect, the Constructor and Destructor
events are fired only once for the component. The Constructor and
Destructor events are not fired each time a new client uses the
component instance. Therefore, to reset the state of a component
instance that is pooled, you need to add logic to the Activate and
Deactivate events, not the Constructor and Destructor events.
The lifecycle of a component
To understand how instance pooling works, you need to understand
the lifecycle of a component instance. Here’s what happens
during the component lifecycle:
- The
component is typically instantiated on the first method invocation. When
this occurs on a component developed in PowerBuilder, Jaguar creates
a new PowerBuilder session for the component to run in. - The PowerBuilder session creates the instance of
the PowerBuilder nonvisual object that represents the Jaguar component.
Creating the object causes the Constructor event to
be fired. - After the object has been instantiated, Jaguar triggers
the Activate event on the nonvisual object
to notify the object that it is about to be used by a new client.
At this point, the component must ensure that its state is ready for
execution. - Jaguar then executes the method called by the client
on the component. - When the component indicates that its work is complete,
Jaguar triggers the Deactivate event to allow
the component to clean up its state. If the Automatic Demarcation/Deactivation
setting for the component is enabled, the Deactivate event is triggered
automatically after each method invocation. If the Automatic Demarcation/Deactivation
setting is disabled, the Deactivate event is triggered when the
component calls the SetComplete (or SetAbort) method of the TransactionServer
context object. - If you’ve selected the Not Supported pooling
option (or set the component’s pooling property to False)
and also scripted the CanBePooled event,
Jaguar triggers this event to ask the component whether it is able
to be pooled at this time. The CanBePooled event allows the component
instance to selectively enable or refuse pooling.
The return value of the CanBePooled event determines whether
the component instance will be pooled. A return value of 1 enables
pooling; a return value of 0 disables pooling. If the CanBePooled
event has not been scripted, then by default the instance will not
be pooled. What happens when the pooling property is enabled When you select the Supported pooling option (or set the component’s pooling
property to True), component instances are always
pooled
and the CanBePooled event is never triggered.
- If an instance is not pooled after deactivation,
Jaguar triggers the Destructor event. Then
it destroys the PowerBuilder object and terminates the runtime session.