session_id
The session id for this particular session. This should be considered an opaque value. If "end_session"
has been called, this returns "undef".
get_latest_cluster_time
my $cluster_time = $session->get_latest_cluster_time;
Returns the latest cluster time, when compared with this session's recorded cluster time and the main
client cluster time. If neither is defined, returns undef.
advance_cluster_time
$session->advance_cluster_time( $cluster_time );
Update the $clusterTime for this session. Stores the value in "cluster_time". If the cluster time
provided is more recent than the sessions current cluster time, then the session will be updated to this
provided value.
Setting the $clusterTime with a manually crafted value may cause a server error. It is recommended to
only use $clusterTime values retrieved from database calls.
advance_operation_time
$session->advance_operation_time( $operation_time );
Update the "operation_time" for this session. If the value provided is more recent than the sessions
current operation time, then the session will be updated to this provided value.
Setting "operation_time" with a manually crafted value may cause a server error. It is recommended to
only use an "operation_time" retrieved from another session or directly from a database call.
start_transaction
$session->start_transaction;
$session->start_transaction( $options );
Start a transaction in this session. If a transaction is already in progress or if the driver can detect
that the client is connected to a topology that does not support transactions, this method will throw an
error.
A hash reference of options may be provided. Valid keys include:
• "readConcern" - The read concern to use for the first command in this transaction. If not defined
here or in the "defaultTransactionOptions" in "options", will inherit from the parent client.
• "writeConcern" - The write concern to use for committing or aborting this transaction. As per
"readConcern", if not defined here then the value defined in "defaultTransactionOptions" will be
used, or the parent client if not defined.
• "readPreference" - The read preference to use for all read operations in this transaction. If not
defined, then will inherit from "defaultTransactionOptions" or from the parent client. This value
will override all other read preferences set in any subsequent commands inside this transaction.
• "maxCommitTimeMS" - The "maxCommitTimeMS" specifies a cumulative time limit in milliseconds for
processing operations on the cursor. MongoDB interrupts the operation at the earliest following
interrupt point.
commit_transaction
$session->commit_transaction;
Commit the current transaction. This will use the writeConcern set on this transaction.
If called when no transaction is in progress, then this method will throw an error.
If the commit operation encounters an error, an error is thrown. If the error is a transient commit
error, the error object will have a label containing "UnknownTransactionCommitResult" as an element and
the commit operation can be retried. This can be checked via the "has_error_label":
LOOP: {
eval {
$session->commit_transaction;
};
if ( my $error = $@ ) {
if ( $error->has_error_label("UnknownTransactionCommitResult") ) {
redo LOOP;
}
else {
die $error;
}
}
}
abort_transaction
$session->abort_transaction;
Aborts the current transaction. If no transaction is in progress, then this method will throw an error.
Otherwise, this method will suppress all other errors (including network and database errors).
end_session
$session->end_session;
Close this particular session and release the session ID for reuse or recycling. If a transaction is in
progress, it will be aborted. Has no effect after calling for the first time.
This will be called automatically by the object destructor.
with_transaction
$session->with_transaction($callback, $options);
Execute a callback in a transaction.
This method starts a transaction on this session, executes $callback, and then commits the transaction,
returning the return value of the $callback. The $callback will be executed at least once.
If the $callback throws an error, the transaction will be aborted. If less than 120 seconds have passed
since calling "with_transaction", and the error has a "TransientTransactionError" label, the transaction
will be restarted and the callback will be executed again. Otherwise, the error will be thrown.
If the $callback succeeds, then the transaction will be committed. If an error is thrown from committing
the transaction, and it is less than 120 seconds since calling "with_transaction", then:
• If the error has a "TransientTransactionError" label, the transaction will be restarted.
• If the error has an "UnknownTransactionCommitResult" label, and is not a "MaxTimeMSExpired" error,
then the commit will be retried.
If the $callback aborts or commits the transaction, no other actions are taken and the return value of
the $callback is returned.
The callback is called with the first (and only) argument being the session, after starting the
transaction:
$session->with_transaction( sub {
# this is the same session as used for with_transaction
my $cb_session = shift;
...
}, $options);
To pass arbitrary arguments to the $callback, wrap your callback in a coderef:
$session->with_transaction(sub { $callback->($session, $foo, ...) }, $options);
Warning: you must either use the provided session within the callback, or otherwise pass the session in
use to the callback. You must pass the $session as an option to all database operations that need to be
included in the transaction.
Warning: The $callback can be called multiple times, so it is recommended to make it idempotent.
A hash reference of options may be provided. these are the same as for "start_transaction".
Install Now
PNG Icons
