Google Cloud Spanner v1 API - Class SessionPool (5.0.0-beta02)

public sealed class SessionPool

Reference documentation and code samples for the Google Cloud Spanner v1 API class SessionPool.

A pool of sessions associated with a SpannerClient. Sessions can be acquired by specifying the desired transaction options, if any. A session/transaction pair is then returned, which should be returned to the pool when it is no longer required. Sessions are kept alive automatically, and retired if they are expired by the server.

Inheritance

object > SessionPool

Namespace

Google.Cloud.Spanner.V1

Assembly

Google.Cloud.Spanner.V1.dll

Constructors

SessionPool(SpannerClient, SessionPoolOptions)

public SessionPool(SpannerClient client, SessionPoolOptions options)

Creates a session pool for the given client.

Parameters
NameDescription
clientSpannerClient

The client to use for this session pool. Must not be null.

optionsSessionPoolOptions

The options for this session pool. Must not be null.

Properties

Options

public SessionPoolOptions Options { get; }

The options governing this session pool.

Property Value
TypeDescription
SessionPoolOptions

Methods

AcquireSessionAsync(DatabaseName, TransactionOptions, CancellationToken)

public Task<PooledSession> AcquireSessionAsync(DatabaseName databaseName, TransactionOptions transactionOptions, CancellationToken cancellationToken)

Asynchronously acquires a session, potentially associated with a transaction. This is equivalent to calling AcquireSessionAsync(SessionPoolSegmentKey, TransactionOptions, CancellationToken) passing a segment key with a null database role.

Parameters
NameDescription
databaseNameGoogle.Cloud.Spanner.Common.V1.DatabaseName

The name of the database to acquire the session for.

transactionOptionsTransactionOptions

The transaction options required for the session. After the operation completes, this value is no longer used, so modifications to the object will not affect the transaction. May be null.

cancellationTokenCancellationToken

An optional token for canceling the call.

Returns
TypeDescription
TaskPooledSession

The PooledSession representing the client, session and transaction.

AcquireSessionAsync(SessionPoolSegmentKey, TransactionOptions, bool, CancellationToken)

public Task<PooledSession> AcquireSessionAsync(SessionPool.SessionPoolSegmentKey key, TransactionOptions transactionOptions, bool singleUseTransaction, CancellationToken cancellationToken)

Asynchronously acquires a session using the given SessionPool.SessionPoolSegmentKey, potentially associated with a transaction.

Parameters
NameDescription
keySessionPoolSessionPoolSegmentKey

The SessionPool.SessionPoolSegmentKey to acquire the session.

transactionOptionsTransactionOptions

The transaction options required for the session. After the operation completes, this value is no longer used, so modifications to the object will not affect the transaction. May be null.

singleUseTransactionbool

Whether the transaction used by this session is single use or not. May only be true if transactionOptions is ReadOnly.

cancellationTokenCancellationToken

An optional token for canceling the call.

Returns
TypeDescription
TaskPooledSession

The PooledSession representing the client, session and transaction.

AcquireSessionAsync(SessionPoolSegmentKey, TransactionOptions, CancellationToken)

public Task<PooledSession> AcquireSessionAsync(SessionPool.SessionPoolSegmentKey key, TransactionOptions transactionOptions, CancellationToken cancellationToken)

Asynchronously acquires a session using the given SessionPool.SessionPoolSegmentKey, potentially associated with a transaction.

Parameters
NameDescription
keySessionPoolSessionPoolSegmentKey

The SessionPool.SessionPoolSegmentKey to acquire the session.

transactionOptionsTransactionOptions

The transaction options required for the session. After the operation completes, this value is no longer used, so modifications to the object will not affect the transaction. May be null.

cancellationTokenCancellationToken

An optional token for canceling the call.

Returns
TypeDescription
TaskPooledSession

The PooledSession representing the client, session and transaction.

CreateDetachedSession(SessionName, ByteString, ModeOneofCase)

public PooledSession CreateDetachedSession(SessionName sessionName, ByteString transactionId, TransactionOptions.ModeOneofCase transactionMode)

Creates a PooledSession with a known name and transaction ID/mode, with the client associated with this pool, but is otherwise not part of this pool. This method does not query the server for the session state. When the returned PooledSession is released, it will not become part of this pool, and the transaction will not be rolled back.

Parameters
NameDescription
sessionNameSessionName

The name of the transaction. Must not be null.

transactionIdByteString

The ID of the transaction. Must not be null.

transactionModeTransactionOptionsModeOneofCase

The mode of the transaction.

Returns
TypeDescription
PooledSession

A PooledSession for the given session and transaction.

Remarks

This is typically used for partitioned queries, where the same session is used across multiple machines, so should not be reused by the pool.

CreateDetachedSession(SessionName, ByteString, ModeOneofCase, Timestamp)

public PooledSession CreateDetachedSession(SessionName sessionName, ByteString transactionId, TransactionOptions.ModeOneofCase transactionMode, Timestamp readTimestamp)

Creates a PooledSession with a known name and transaction ID/mode, with the client associated with this pool, but is otherwise not part of this pool. This method does not query the server for the session state. When the returned PooledSession is released, it will not become part of this pool, and the transaction will not be rolled back.

Parameters
NameDescription
sessionNameSessionName

The name of the transaction. Must not be null.

transactionIdByteString

The ID of the transaction. Must not be null.

transactionModeTransactionOptionsModeOneofCase

The mode of the transaction.

readTimestampTimestamp

The read timestamp of the transaction.

Returns
TypeDescription
PooledSession

A PooledSession for the given session and transaction.

Remarks

This is typically used for partitioned queries, where the same session is used across multiple machines, so should not be reused by the pool.

GetSegmentStatisticsSnapshot(DatabaseName)

public SessionPool.SessionPoolSegmentStatistics GetSegmentStatisticsSnapshot(DatabaseName databaseName)

Provides a snapshot of statistics for the pool associated with the given database. This is equivalent to calling GetSegmentStatisticsSnapshot(SessionPoolSegmentKey) passing a segment key with a null database role.

Parameter
NameDescription
databaseNameGoogle.Cloud.Spanner.Common.V1.DatabaseName
Returns
TypeDescription
SessionPoolSessionPoolSegmentStatistics

A snapshot of statistics for this pool.

GetSegmentStatisticsSnapshot(SessionPoolSegmentKey)

public SessionPool.SessionPoolSegmentStatistics GetSegmentStatisticsSnapshot(SessionPool.SessionPoolSegmentKey key)

Provides a snapshot of statistics for the pool associated with the given SessionPool.SessionPoolSegmentKey.

Parameter
NameDescription
keySessionPoolSessionPoolSegmentKey
Returns
TypeDescription
SessionPoolSessionPoolSegmentStatistics

A snapshot of statistics for this pool.

GetStatisticsSnapshot()

public SessionPool.Statistics GetStatisticsSnapshot()

Provides a snapshot of statistics for this pool.

Returns
TypeDescription
SessionPoolStatistics

A snapshot of statistics for this pool.

GetStatisticsSnapshot(DatabaseName)

[Obsolete("Use the overload GetSegmentStatisticsSnapshot(DatabaseName) instead.")]
public SessionPool.DatabaseStatistics GetStatisticsSnapshot(DatabaseName databaseName)

Provides a snapshot of statistics for a database-specific pool. This is equivalent to calling GetSegmentStatisticsSnapshot(SessionPoolSegmentKey) passing a segment key with a null database role.

Parameter
NameDescription
databaseNameGoogle.Cloud.Spanner.Common.V1.DatabaseName
Returns
TypeDescription
SessionPoolDatabaseStatistics

A snapshot of statistics for this pool.

ShutdownPoolAsync(DatabaseName, CancellationToken)

public Task ShutdownPoolAsync(DatabaseName databaseName, CancellationToken cancellationToken)

Shuts down the session pool associated with the given database name. Further attempts to acquire sessions will fail immediately. This is equivalent to calling ShutdownPoolAsync(SessionPoolSegmentKey, CancellationToken) passing a segment key with a null database role.

Parameters
NameDescription
databaseNameGoogle.Cloud.Spanner.Common.V1.DatabaseName

The database whose session pool should be shut down. Must not be null.

cancellationTokenCancellationToken

An optional token for canceling the returned task. This does not cancel the shutdown itself.

Returns
TypeDescription
Task

A task which will complete when the session pool has finished shutting down.

Remarks

This call will delete all pooled sessions, and wait for all active sessions to be released back to the pool and also deleted.

ShutdownPoolAsync(SessionPoolSegmentKey, CancellationToken)

public Task ShutdownPoolAsync(SessionPool.SessionPoolSegmentKey key, CancellationToken cancellationToken)

Shuts down the session pool of the given SessionPoolSegmentKey. Further attempts to acquire sessions will fail immediately.

Parameters
NameDescription
keySessionPoolSessionPoolSegmentKey

The SessionPool.SessionPoolSegmentKey whose session pool should be shutdown.

cancellationTokenCancellationToken

An optional token for canceling the returned task. This does not cancel the shutdown itself.

Returns
TypeDescription
Task

A task which will complete when the session pool has finished shutting down.

Remarks

This call will delete all pooled sessions, and wait for all active sessions to be released back to the pool and also deleted.

WhenPoolReady(DatabaseName, CancellationToken)

public Task WhenPoolReady(DatabaseName databaseName, CancellationToken cancellationToken = default)

Returns a task indicating when the session pool associated with the given database name is populated up to its minimum size. This is equivalent to calling WhenPoolReady(SessionPoolSegmentKey, CancellationToken) passing a segment key with a null database role.

Parameters
NameDescription
databaseNameGoogle.Cloud.Spanner.Common.V1.DatabaseName

The database whose session pool should be populated. Must not be null.

cancellationTokenCancellationToken

An optional token for canceling the call.

Returns
TypeDescription
Task

A task which will complete when the session pool has reached its minimum size.

Remarks

If the pool is unhealthy or becomes unhealthy before it reaches its minimum size, the returned task will be faulted with an RpcException.

WhenPoolReady(SessionPoolSegmentKey, CancellationToken)

public Task WhenPoolReady(SessionPool.SessionPoolSegmentKey key, CancellationToken cancellationToken = default)

Returns a task indicating when the session pool for the given SessionPool.SessionPoolSegmentKey is populated up to its minimum size.

Parameters
NameDescription
keySessionPoolSessionPoolSegmentKey

The SessionPool.SessionPoolSegmentKey whose session pool should be populated.

cancellationTokenCancellationToken

An optional token for canceling the call.

Returns
TypeDescription
Task

A task which will complete when the session pool has reached its minimum size.

Remarks

If the pool is unhealthy or becomes unhealthy before it reaches its minimum size, the returned task will be faulted with an RpcException.