| Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-01 |
|
|
View PDF |
| Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-01 |
|
|
View PDF |
This section describes the OCI pin unpin, and free functions.
Table 17-11 Pin, Unpin, and Free Functions
| Function/Page | Purpose |
|---|---|
| OCICacheFree() |
Free objects in the cache |
| OCICacheUnpin() |
Unpin persistent objects in cache or connection |
| OCIObjectArrayPin() |
Pin an array of references |
| OCIObjectFree() |
Free a previously allocated object |
| OCIObjectPin() |
Pin an object |
| OCIObjectPinCountReset() |
Unpin an object to zero pin count |
| OCIObjectPinTable() |
Pin a table object with a given duration |
| OCIObjectUnpin() |
Unpin an object |
Purpose
Frees all objects and values in the cache for the specified connection.
Syntax
sword OCICacheFree ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc );
Parameters
The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
An OCI service context.
Comments
If a connection is specified, this function frees the persistent objects, transient objects and values allocated for that connection. Otherwise, all persistent objects, transient objects and values in the object cache are freed. Objects are freed regardless of their pin count.
Related Functions
Purpose
Unpins persistent objects.
Syntax
sword OCICacheUnpin ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc );
Parameters
The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
An OCI service context handle. The objects on the specified connection are unpinned.
Comments
This function completely unpins all of the persistent objects for the given connection. The pin count for the objects is reset to zero.
|
See Also: For more information about pinning and unpinning, see "Pinning an Object", and "Pin Count and Unpinning". |
Related Functions
Purpose
Pins an array of references.
Syntax
sword OCIObjectArrayPin ( OCIEnv *env,
OCIError *err,
OCIRef **ref_array,
ub4 array_size,
OCIComplexObject **cor_array,
ub4 cor_array_size,
OCIPinOpt pin_option,
OCIDuration pin_duration,
OCILockOpt lock,
dvoid **obj_array,
ub4 *pos );
Parameters
The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Array of references to be pinned
Number of elements in the array of references
An array of COR handles corresponding to the objects being pinned.
The number of elements in cor_array.
Pin option.
Pin duration. See OCIObjectPin().
Lock option. See OCIObjectPin().
If this argument is not NULL, the pinned objects will be returned in the array. The user must allocate this array with element type being dvoid *. The size of this array is identical to array_size.
If there is an error, this argument indicates the element that is causing the error. Note that this argument is set to 1 for the first element in the ref_array.
Comments
All the pinned objects are retrieved from the database in one network round trip. If the user specifies an output array (obj_array), then the address of the pinned objects will be assigned to the elements in the array.
Related Functions
Purpose
Frees and unpins an object instance.
Syntax
sword OCIObjectFree ( OCIEnv *env,
OCIError *err,
dvoid *instance,
ub2 flags );
Parameters
The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Pointer to a standalone instance. If it is an object, it must be pinned.
If OCI_OBJECTFREE_FORCE is passed, free the object even if it is pinned or dirty. If OCI_OBJECTFREE_NONULL is passed, the NULL structure is not freed.
Comments
This function deallocates all the memory allocated for an object instance, including the NULL structure. The following rules apply for different instance types:
This function returns an error if the client is attempting to free a dirty persistent object that has not been flushed. The client should either flush the persistent object, unmark it, or set the parameter flags to OCI_OBJECTFREE_FORCE.
This function calls OCIObjectUnpin() once to check if the object can be completely unpin. If it succeeds, the rest of the function proceeds to free the object. If it fails, then an error is returned unless the parameter flags is set to OCI_OBJECTFREE_FORCE.
Freeing a persistent object in memory does not change the persistent state of that object at the server. For example, the object remains locked after the object is freed.
This function will call OCIObjectUnpin() once to check if the object can be completely unpin. If it succeeds, the rest of the function will proceed to free the object. If it fails, then an error is returned unless the parameter flags is set to OCI_OBJECTFREE_FORCE.
The memory of the object is freed immediately.
Related Functions
Purpose
Pin a referenceable object.
Syntax
sword OCIObjectPin ( OCIEnv *env,
OCIError *err,
OCIRef *object_ref,
OCIComplexObject *corhdl,
OCIPinOpt pin_option,
OCIDuration pin_duration,
OCILockOpt lock_option,
dvoid **object );
Parameters
The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
The reference to the object.
Handle for complex object retrieval.
Used to specify the copy of the object that is to be retrieved.
The duration of which the object is being accessed by a client. The object is implicitly unpinned at the end of the pin duration. If OCI_DURATION_NULL is passed, there is no pin promotion if the object is already loaded into the cache. If the object is not yet loaded, then the pin duration is set to OCI_DURATION_DEFAULT in the case of OCI_DURATION_NULL.
Lock option (for example, exclusive). If a lock option is specified, the object is locked in the server. Note, the lock status of an object can also be retrieved by calling OCIObjectIsLocked(). Valid values include:
OCI_LOCK_NONE - for no lock
OCI_LOCK_X - for an exclusive lock
OCI_LOCK_X_NOWAIT - for an exclusive lock with the NOWAIT option.
The pointer to the pinned object.
Comments
This function pins a referenceable object instance given the object reference. The process of pinning serves two purposes:
locate an object given its reference. This is done by the object cache which keeps track of the objects in the object cache.
notify the object cache that a persistent object is being in use such that the persistent object cannot be aged out. Since a persistent object can be loaded from the server whenever is needed, the memory utilization can be increased if a completely unpinned persistent object can be freed (aged out), even before the allocation duration is expired. An object can be pinned many times. A pinned object will remain in memory until it is completely unpinned.
When pinning a persistent object, if it is not in the cache, the object will be fetched from the persistent store. The allocation duration of the object is session. If the object is already in the cache, it is returned to the client. The object will be locked in the server if a lock option is specified.
This function will return an error for a non-existent object.
A pin option is used to specify the copy of the object that is to be retrieved:
If pin_option is OCI_PIN_ANY (pin any), then if the object is already in the object cache, return this object. Otherwise, the object is retrieved from the database. In this case, it is the same as OCI_PIN_LATEST. This option is useful when the client knows that he has the exclusive access to the data in a session.
If pin_option is OCI_PIN_LATEST (pin latest), if the object is not locked, it is retrieved from the database. If the object is cached, it is refreshed with the latest version. See OCIObjectRefresh() for more information about refreshing. If the object is already pinned in the cache and marked dirty, then a pointer to that object is returned. The object will not be refreshed from the database.
If pin_option is OCI_PIN_RECENT (pin recent), if the object is loaded into the cache in the current transaction, the object is returned. If the object is not loaded in the current transaction, the object is refreshed from the server.
This function will return an error if the transient object has already been freed. This function does not return an error if an exclusive lock is specified in the lock option.
Related Functions
OCIObjectUnpin(), OCIObjectPinCountReset()
Purpose
Completely unpins an object, setting its pin count to zero.
Syntax
sword OCIObjectPinCountReset ( OCIEnv *env,
OCIError *err,
dvoid *object );
Parameters
The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
A pointer to an object, which must already be pinned.
Comments
This function completely unpins an object, setting its pin count to zero. When an object is completely unpinned, it can be freed implicitly by the OCI at any time without error. The following rules apply for specific object types:
When a persistent object is completely unpinned, it becomes a candidate for aging. The memory of an object is freed when it is aged out. Aging is used to maximize the utilization of memory. An dirty object cannot be aged out unless it is flushed.
The pin count of the object is decremented. A transient can be freed only at the end of its allocation duration or when it is explicitly freed by calling OCIObjectFree().
This function will return an error for value.
Related Functions
OCIObjectPin(), OCIObjectUnpin()
Purpose
Pins a table object for a specified duration.
Syntax
sword OCIObjectPinTable ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc,
CONST OraText *schema_name,
ub4 s_n_length,
CONST OraText *object_name,
ub4 o_n_length,
dvoid *not_used,
OCIDuration pin_duration,
dvoid **object );
Parameters
The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
The OCI service context handle.
The schema name of the table.
The length of the schema name indicated in schema_name, in bytes.
The name of the table.
The length of the table name specified in object_name, in bytes.
This parameter is not currently used. Pass as NULL.
The pin duration.
The pinned table object.
Comments
This function pins a table object with the specified pin duration. The client can unpin the object by calling OCIObjectUnpin().
The table object pinned by this call can be passed as a parameter to OCIObjectNew() to create a standalone persistent object.
|
Note: The TDO (array of TDOs or table definition) obtained by this function will belong to the logical partition of the cache corresponding to the service handle (connection) passed in. If TDOs or tables are used across logical partitions, then the behavior is not known and may change between releases. |
Related Functions
OCIObjectPin(), OCIObjectUnpin()
Purpose
Unpins an object.
Syntax
sword OCIObjectUnpin ( OCIEnv *env,
OCIError *err,
dvoid *object );
Parameters
The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
A pointer to an object, which must already be pinned.
Comments
There is a pin count associated with each object which is incremented whenever an object is pinned. When the pin count of the object is zero, the object is said to be completely unpinned. An unpinned object can be freed implicitly by the OCI at any time without error.
This function unpins an object. An object is completely unpinned when any of the following is true:
The object's pin count reaches zero (that is, it is unpinned a total of N times after being pinned a total of N times).
It is the end of the object's pin duration.
The function OCIObjectPinCountReset() is called on the object.
When an object is completely unpinned, it can be freed implicitly by the OCI at any time without error.
The following rules apply for unpinning different types of objects:
When a persistent object is completely unpinned, it becomes a candidate for aging. The memory of an object is freed when it is aged out. Aging is used to maximize the utilization of memory. An dirty object cannot be aged out unless it is flushed.
The pin count of the object is decremented. A transient can be freed only at the end of its allocation duration or when it is explicitly deleted by calling OCIObjectFree().
This function returns an error for values.
Related Functions
