ObjectControl Interface

You implement the ObjectControl interface when you want to define context-specific initialization and cleanup procedures for your MTS objects and specify whether or not the objects can be recycled. Implementing the ObjectControl interface is optional.

On This Page

Remarks
Activate Method
CanBePooled Method
Deactivate Method

Remarks

If you implement the ObjectControl interface in your component, the MTS run-time environment automatically calls the ObjectControl methods on your objects at the appropriate times.

When an object supports the ObjectControl interface, MTS calls its Activate method once for each time the object is activated. The Activate method is called before any of the object's other methods are called. You can use this method to perform any context-specific initialization an object may require.

MTS calls the object's Deactivate method each time the object is deactivated. This can be the result of the object returning from a method in which it calls SetComplete or SetAbort, or due to the root of the object's transaction, causing the transaction to complete. You use the Deactivate method to clean up state that you initialized in the Activate method.

After calling the Deactivate method, the MTS run-time environment calls the CanBePooled method. If this method returns True, the deactivated object is placed in an object pool for reuse. If the CanBePooled method returns False, the object is released in the usual way.

Note: On systems that don't support object pooling, the value returned by this method is ignored.

The ObjectControl interface is not accessible to an object's clients or to the object itself. Only the MTS run-time environment can invoke the ObjectControl methods.

The ObjectControl interface provides the following methods.

See Also

Deactivating Objects, Object Pooling and Recycling

Activate Method

Implementing this method allows an MTS object to perform context-specific initialization whenever it's activated. This method is called by the MTS run-time environment before any other methods are called on the object.

Applies To

ObjectContext Object

Syntax
objectcontrol. Activate

The objectcontrol placeholder represents is an object variable that evaluates to an ObjectControl object.

Remarks

Whenever a client calls an MTS object that isn't already activated, the MTS run-time environment automatically activates the object. This is called just-in-time activation. For components that support the ObjectControl interface, MTS invokes the object's Activate method before passing the client's method call on to the object. This allows objects to do context-specific initialization.

If you need to perform any initialization that involves the ObjectContext, you should implement the Activate method and place all your context-specific initialization procedures there.

For example, you can use the Activate method to obtain a reference to an object's context and store it in a member variable. Then the context is available to any method that requires it, and you don't have to acquire a new one and then release it every time you use it. Once you have a reference to the object's context, you can use the IObjectContext methods to check whether security is enabled, whether the object is executing in a transaction, or whether the caller is in a particular role.

If you're enabling object recycling (returning True from the CanBePooled method), the Activate method must be able to handle both newly created and recycled objects. When the Activate method returns, there should be no distinguishable difference between a new object and a recycled one.

Example

See Also

Deactivating Objects, Object Pooling and Recycling

Activate Method Example

Implements ObjectControl
Dim context As ObjectContext
Option Explicit
Private Sub ObjectControl_Activate()
    ' Get a reference to the object's context here,
    ' so it can be used by any method that may be 
    ' called during this activation of the object.
    Set context = GetObjectContext()
End Sub

CanBePooled Method

Implementing this method allows an MTS object to notify the MTS run-time environment of whether it can be pooled for reuse. Return True if you want the object to be pooled for reuse, or False if not.

Applies To

ObjectContext Object

Syntax
objectcontrol. CanBePooled (True | False )

The objectcontrol placeholder represents is an object variable that evaluates to an ObjectControl object.

Return Values

True

Notifies the MTS run-time environment that it can pool this object on deactivation for later reuse.

False

Notifies the MTS run-time environment that it should not pool this object on deactivation, but should release its last reference to the object so that the object will be destroyed.

Remarks

When an object returns True from the CanBePooled method, it indicates to the MTS run-time environment that it can be added to an object pool after deactivation rather than being destroyed. Whenever an instance is required, one is drawn from the pool rather than created.

The way recycling works is that an object cleans itself up in its Deactivate method and is returned to an object pool. Later, when an instance of the same component is needed, the cleaned up object can be reused. For this to work, an object must be accessible on different threads each time it's activated. Recycling isn't possible under the apartment threading model because, in that model, although an object can be instantiated on any thread, it can only be used by the thread on which it was instantiated. If you want instances of a component to be recyclable, you should register the component with the ThreadingModel Registry value set to Both. This indicates to MTS that the component's objects can be called from different threads.

In MTS, these objects will run under the apartment threading model and won't be recycled even if they return True from the CanBePooled method. However, if you configure a component to support both threading models, the component will run under the current version of MTS and will also be able to take advantage of recycling as soon as it becomes available, without any changes to the code.

Deciding whether to enable recycling is a matter of weighing the costs and benefits. Recycling requires writing additional code, and there's a risk that some state may be inadvertently retained from one activation to the next. When you allow objects to be pooled, you have to be very careful in your Activate and Deactivate methods to ensure that a recycled object is always restored to a state that's equivalent to the state of a newly created object. Another consideration to take into account is the amount of resources required to maintain an object pool. Objects that hold a lot of resources can be expensive to pool. However, in certain situations, recycling can be extremely efficient, resulting in improved performance and increased scalability. The trade-off is between the cost of holding onto resources while objects are pooled (and inactive) versus the cost of creating and destroying the resources.

It's usually best to enable recycling for objects that cost more to create than they cost to reinitialize. For example, if a component contains a complex structure, and that structure can be reused, it could save a lot of time if the structure didn't have to be recreated every time an instance of the component was activated. This is a case in which you might want to enable recycling, which you would do by returning True from the CanBePooled method.

The Activate method is called whether a new instance is created or a recycled instance is drawn from the pool. Similarly, the Deactivate method is called every time the object is deactivated, whether it's being destroyed or returned to the pool for recycling.

So, in this example, you'd use the object's Activate method to initialize, or reinitialize, the structure that's being reused, and you'd use the Deactivate method to restore the object to a state that the Activate method can handle. (The Activate method must be able to handle both new objects and reused objects drawn from the pool.) This combined use of the Activate, Deactivate, and CanBePooled methods eliminates the need to recreate reusable resources every time an instance is activated.

For some objects, recycling isn't efficient. For example, if an object acquires a lot of state during its lifetime that isn't reusable, and has little to do during its construction, it's usually cheaper to create a new instance whenever one is needed. In that case, you would return False from the CanBePooled method.

Note: Returning True from the CanBePooled method doesn't guarantee that objects will be recycled; it only gives the MTS run-time environment permission to recycle them. On systems that don't support object pooling, a return value of True is ignored. Returning False from the CanBePooled method guarantees that instances of a component aren't recycled.

Example

See Also

Deactivating Objects, Object Pooling and Recycling

CanBePooled Method Example

Implements ObjectControl
Dim context As ObjectContext
Option Explicit
Private Function ObjectControl_CanBePooled() As Boolean
    ' This object should not be recycled,
    ' so return false.
    ObjectControl_CanBePooled = False
End Function

Deactivate Method

Implementing this method allows an MTS object to perform any cleanup required before it's recycled or destroyed. This method is called by the MTS run-time environment whenever an object is deactivated.

Applies To

ObjectContext Object

Syntax
objectcontrol . Deactivate

The objectcontrol placeholder represents is an object variable that evaluates to an ObjectControl object.

Remarks

The MTS run-time environment calls the Deactivatemethod whenever an object that supports the ObjectControl interface is deactivated. An object is deactivated when it returns from a method in which it called SetComplete or SetAbort, when the transaction in which it executed is committed or aborted, or when the last client to hold a reference on it releases its reference.

If the component supports recycling (returns True from the CanBePooledmethod), you should use the Deactivate method to reset the object's state to the state in which the Activate method expects to find it. You can also use the Deactivate method to release the object's ObjectContext or to do other context-specific cleanup. Even if an object supports recycling, it can be beneficial to release certain reusable resources in its Deactivate method. For example, ODBC provides its own connection pooling. It's more efficient to pool a database connection in a general connection pool where it can be used by other objects than it is to keep it tied to a specific object in an object pool.

Example

See Also

Deactivating Objects, Object Pooling and Recycling

Deactivate Method Example

Implements ObjectControl
Dim objcontext As ObjectContext
Option Explicit
Private Sub ObjectControl_Deactivate()
    ' Perform any necessary cleanup here.
    Set objcontext = Nothing
End Sub