This section describes the OCI pin unpin, and free functions.
Table 17-11 Pin, Unpin, and Free Functions
Function/Page | Purpose |
---|---|
Free objects in the cache |
|
Unpin persistent objects in cache or connection |
|
Pin an array of references |
|
Free a previously allocated object |
|
Pin an object |
|
Unpin an object to zero pin count |
|
Pin a table object with a given duration |
|
Unpin an object |
Frees all objects and values in the cache for the specified connection.
sword OCICacheFree ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc );
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.
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.
See Also:
See "OCIObjectFree()" for more information about freeing an instance.Unpins persistent objects.
sword OCICacheUnpin ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc );
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.
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".Pins an array of references.
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 );
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.
See Also:
"OCIObjectPin()"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
.
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.
Frees and unpins an object instance.
sword OCIObjectFree ( OCIEnv *env, OCIError *err, dvoid *instance, ub2 flags );
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.
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.
Pin a referenceable object.
sword OCIObjectPin ( OCIEnv *env, OCIError *err, OCIRef *object_ref, OCIComplexObject *corhdl, OCIPinOpt pin_option, OCIDuration pin_duration, OCILockOpt lock_option, dvoid **object );
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.
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.
See Also:
See "OCIObjectUnpin()".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.
OCIObjectUnpin(), OCIObjectPinCountReset()
Completely unpins an object, setting its pin count to zero.
sword OCIObjectPinCountReset ( OCIEnv *env, OCIError *err, dvoid *object );
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.
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.
See Also:
"Pin Count and Unpinning"OCIObjectPin(), OCIObjectUnpin()
Pins a table object for a specified duration.
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 );
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.
See Also:
"OCIObjectPin()".The pinned table object.
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.OCIObjectPin(), OCIObjectUnpin()
Unpins an object.
sword OCIObjectUnpin ( OCIEnv *env, OCIError *err, dvoid *object );
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.
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.