MongoDB::ClientSession - phpMan

Command: man perldoc info search(apropos)  


MongoDB::ClientSession(3pm)    User Contributed Perl Documentation    MongoDB::ClientSession(3pm)

NAME
       MongoDB::ClientSession - MongoDB session and transaction management

VERSION
       version v2.2.2

SYNOPSIS
           my $session = $client->start_session( $options );

           # use session in operations
           my $result = $collection->find( { id => 1 }, { session => $session } );

           # use sessions for transactions
           $session->start_transaction;
           ...
           if ( $ok ) {
               $session->commit_transaction;
           }
           else {
               $session->abort_transaction;
           }

DESCRIPTION
       This class encapsulates an active session for use with the current client.  Sessions
       support is new with MongoDB 3.6, and can be used in replica set and sharded MongoDB
       clusters.

   Explicit and Implicit Sessions
       If you specifically apply a session to an operation, then the operation will be performed
       with that session id. If you do not provide a session for an operation, and the server
       supports sessions, then an implicit session will be created and used for this operation.

       The only exception to this is for unacknowledged writes - the driver will not provide an
       implicit session for this, and if you provide a session then the driver will raise an
       error.

   Cursors
       During cursors, if a session is not provided then an implicit session will be created
       which is then used for the lifetime of the cursor. If you provide a session, then note
       that ending the session and then continuing to use the cursor will raise an error.

   Thread Safety
       NOTE: Per threads documentation, use of Perl threads is discouraged by the maintainers of
       Perl and the MongoDB Perl driver does not test or provide support for use with threads.

       Sessions are NOT thread safe, and should only be used by one thread at a time.  Using a
       session across multiple threads is unsupported and unexpected issues and errors may occur.
       Note that the driver does not check for multi-threaded use.

   Transactions
       A session may be associated with at most one open transaction (on MongoDB 4.0+).  For
       detailed instructions on how to use transactions with drivers, see the MongoDB manual
       page: Transactions <https://docs.mongodb.com/master/core/transactions>.

ATTRIBUTES
   client
       The client this session was created using.  Sessions may only be used with the client that
       created them.

   cluster_time
       Stores the last received $clusterTime for the client session. This is an opaque value, to
       set it use the advance_cluster_time function.

   options
       Options provided for this particular session. Available options include:

       o   "causalConsistency" - If true, will enable causalConsistency for this session. For
           more information, see MongoDB documentation on Causal Consistency
           <https://docs.mongodb.com/manual/core/read-isolation-consistency-recency/#causal-
           consistency>. Note that causalConsistency does not apply for unacknowledged writes.
           Defaults to true.

       o   "defaultTransactionOptions" - Options to use by default for transactions created with
           this session. If when creating a transaction, none or only some of the transaction
           options are defined, these options will be used as a fallback. Defaults to inheriting
           from the parent client. See "start_transaction" for available options.

   operation_time
       The last operation time. This is updated when an operation is performed during this
       session, or when "advance_operation_time" is called. Used for causal consistency.

METHODS
   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:

       o   "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.

       o   "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.

       o   "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.

       o   "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:

       o   If the error has a "TransientTransactionError" label, the transaction will be
           restarted.

       o   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".

AUTHORS
       o   David Golden <david AT mongodb.com>

       o   Rassi <rassi AT mongodb.com>

       o   Mike Friedman <friedo AT friedo.com>

       o   Kristina Chodorow <k.chodorow AT gmail.com>

       o   Florian Ragwitz <rafl AT debian.org>

COPYRIGHT AND LICENSE
       This software is Copyright (c) 2020 by MongoDB, Inc.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004

perl v5.30.3                                2020-08-15                MongoDB::ClientSession(3pm)

Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-11-13 19:33 @98.84.25.165 CrawledBy CCBot/2.0 (https://commoncrawl.org/faq/)
Valid XHTML 1.0!Valid CSS!