Current File : /home/opti/optisoftcom-new/perl/usr/man/man3/MongoDB::ClientSession.3pm
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MongoDB::ClientSession 3"
.TH MongoDB::ClientSession 3 "2018-11-30" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MongoDB::ClientSession \- MongoDB session and transaction management
.SH "VERSION"
.IX Header "VERSION"
version v2.0.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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;
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SS "Explicit and Implicit Sessions"
.IX Subsection "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.
.PP
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.
.SS "Cursors"
.IX Subsection "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.
.SS "Thread Safety"
.IX Subsection "Thread Safety"
Sessions are \s-1NOT\s0 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.
.SS "Transactions"
.IX Subsection "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>.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "client"
.IX Subsection "client"
The client this session was created using. Sessions may only be used
with the client that created them.
.SS "cluster_time"
.IX Subsection "cluster_time"
Stores the last received \f(CW$clusterTime\fR for the client session. This is an
opaque value, to set it use the advance_cluster_time function.
.SS "options"
.IX Subsection "options"
Options provided for this particular session. Available options include:
.IP "\(bu" 4
\&\f(CW\*(C`causalConsistency\*(C'\fR \- 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.
.IP "\(bu" 4
\&\f(CW\*(C`defaultTransactionOptions\*(C'\fR \- 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 \*(L"start_transaction\*(R" for available options.
.SS "operation_time"
.IX Subsection "operation_time"
The last operation time. This is updated when an operation is performed during
this session, or when \*(L"advance_operation_time\*(R" is called. Used for causal
consistency.
.SH "METHODS"
.IX Header "METHODS"
.SS "session_id"
.IX Subsection "session_id"
The session id for this particular session. This should be considered
an opaque value. If \f(CW\*(C`end_session\*(C'\fR has been called, this returns \f(CW\*(C`undef\*(C'\fR.
.SS "get_latest_cluster_time"
.IX Subsection "get_latest_cluster_time"
.Vb 1
\& my $cluster_time = $session\->get_latest_cluster_time;
.Ve
.PP
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.
.SS "advance_cluster_time"
.IX Subsection "advance_cluster_time"
.Vb 1
\& $session\->advance_cluster_time( $cluster_time );
.Ve
.PP
Update the \f(CW$clusterTime\fR for this session. Stores the value in
\&\*(L"cluster_time\*(R". If the cluster time provided is more recent than the sessions
current cluster time, then the session will be updated to this provided value.
.PP
Setting the \f(CW$clusterTime\fR with a manually crafted value may cause a server
error. It is recommended to only use \f(CW$clusterTime\fR values retrieved from
database calls.
.SS "advance_operation_time"
.IX Subsection "advance_operation_time"
.Vb 1
\& $session\->advance_operation_time( $operation_time );
.Ve
.PP
Update the \*(L"operation_time\*(R" 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.
.PP
Setting \f(CW\*(C`operation_time\*(C'\fR with a manually crafted value may cause a server
error. It is recommended to only use an \f(CW\*(C`operation_time\*(C'\fR retrieved from
another session or directly from a database call.
.SS "start_transaction"
.IX Subsection "start_transaction"
.Vb 2
\& $session\->start_transaction;
\& $session\->start_transaction( $options );
.Ve
.PP
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.
.PP
A hash reference of options may be provided. Valid keys include:
.IP "\(bu" 4
\&\f(CW\*(C`readConcern\*(C'\fR \- The read concern to use for the first command in this transaction. If not defined here or in the \f(CW\*(C`defaultTransactionOptions\*(C'\fR in \*(L"options\*(R", will inherit from the parent client.
.IP "\(bu" 4
\&\f(CW\*(C`writeConcern\*(C'\fR \- The write concern to use for committing or aborting this transaction. As per \f(CW\*(C`readConcern\*(C'\fR, if not defined here then the value defined in \f(CW\*(C`defaultTransactionOptions\*(C'\fR will be used, or the parent client if not defined.
.IP "\(bu" 4
\&\f(CW\*(C`readPreference\*(C'\fR \- The read preference to use for all read operations in this transaction. If not defined, then will inherit from \f(CW\*(C`defaultTransactionOptions\*(C'\fR or from the parent client. This value will override all other read preferences set in any subsequent commands inside this transaction.
.SS "commit_transaction"
.IX Subsection "commit_transaction"
.Vb 1
\& $session\->commit_transaction;
.Ve
.PP
Commit the current transaction. This will use the writeConcern set on this
transaction.
.PP
If called when no transaction is in progress, then this method will throw
an error.
.PP
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 \*(L"UnknownTransactionCommitResult\*(R" as an element and the commit
operation can be retried. This can be checked via the \f(CW\*(C`has_error_label\*(C'\fR:
.PP
.Vb 10
\& LOOP: {
\& eval {
\& $session\->commit_transaction;
\& };
\& if ( my $error = $@ ) {
\& if ( $error\->has_error_label("UnknownTransactionCommitResult") ) {
\& redo LOOP;
\& }
\& else {
\& die $error;
\& }
\& }
\& }
.Ve
.SS "abort_transaction"
.IX Subsection "abort_transaction"
.Vb 1
\& $session\->abort_transaction;
.Ve
.PP
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).
.SS "end_session"
.IX Subsection "end_session"
.Vb 1
\& $session\->end_session;
.Ve
.PP
Close this particular session and release the session \s-1ID\s0 for reuse or
recycling. If a transaction is in progress, it will be aborted. Has no
effect after calling for the first time.
.PP
This will be called automatically by the object destructor.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <david@mongodb.com>
.IP "\(bu" 4
Rassi <rassi@mongodb.com>
.IP "\(bu" 4
Mike Friedman <friedo@friedo.com>
.IP "\(bu" 4
Kristina Chodorow <k.chodorow@gmail.com>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2018 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\& The Apache License, Version 2.0, January 2004
.Ve
Mini Shell