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

public sealed class PooledSession : IDisposable

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

A session from a SessionPool, with an associated transaction if requested. Instances must be released back to the pool via ReleaseToPool(bool).

Inheritance

object > PooledSession

Implements

IDisposable

Inherited Members

object.GetHashCode()

object.GetType()

object.ToString()

Namespace

Google.Cloud.Spanner.V1

Assembly

Google.Cloud.Spanner.V1.dll

Remarks

Each method in this class modifies requests passed as arguments to RPC methods, to populate the session and transaction properties.

This class keeps track of successful RPCs to update its internal refresh timer. This can't be applied for streaming SQL calls, as ReliableStreamReader performs the actual RPCs in that case.

Properties

ReadTimestamp

public Timestamp ReadTimestamp { get; }

The read timestamp of the transaction. May be null.

Property Value
Type	Description
`Timestamp`

Remarks

Will be set iif a transaction has been started and TransactionOptions represents read-only options with ReturnReadTimestamp set to true or if this session was created using CreateDetachedSession(SessionName, ByteString, ModeOneofCase, Timestamp) and a value was provided for the Timestamp parameter.

SessionName

public SessionName SessionName { get; }

The name of the session. This is never null.

Property Value
Type	Description
`SessionName`

TransactionId

public ByteString TransactionId { get; }

The ID of the transaction. May be null.

Property Value
Type	Description
`ByteString`

Remarks

Transactions are acquired when they are needed so this will be null in the following cases:

TransactionOptions is None, including when the session is idle in the pool.
SingleUseTransaction is true. No transactions will exist client side.
The session has been acquired from the pool with some transaction options but no command execution has been attempted since.
The first command execution is underway and the transaction is being created either by inlining or explicitly.

Methods

CommitAsync(CommitRequest, CallSettings)

public Task<CommitResponse> CommitAsync(CommitRequest request, CallSettings callSettings)

Executes a Commit RPC asynchronously.

Parameters
Name	Description
`request`	`CommitRequest` The commit request. Must not be null. The request will be modified with session and transaction details from this object.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`TaskCommitResponse`	A task representing the asynchronous operation. When the task completes, the result is the response from the RPC.

DetachFromPool()

public void DetachFromPool()

Detaches this session from the session pool from which it was acquired, so that the session pool stops tracking this session and counting it as active. This method should only be called once per instance; subsequent calls are ignored. No other methods can be called after this.

Remarks

This method should be called only for sessions that are meant to be explicitly shared across processes. Note that we don't attempt to rollback a transaction that is being detached, or attempt to delete the session, under the assumption that it will be reused across processes. If there's a process capable of knowing when all other processes are done using the session, then that process could call CreateDetachedSession(SessionName, ByteString, ModeOneofCase) (or an overload) to create an instance of PooledSession representing the shared transaction and then call ReleaseToPool(bool) passing true to force session deletion and clean up resources. Else, the application can rely on Spanner service garbage collection to clean up this session once it becomes stale.

Dispose()

public void Dispose()

Releases this session back to the session pool. This method should only be called once per instance; subsequent calls are ignored. No other methods can be called after this.

Remarks

This method is equivalent to calling ReleaseToPool(bool) with an argument of false.

ExecuteBatchDmlAsync(ExecuteBatchDmlRequest, CallSettings)

public Task<ExecuteBatchDmlResponse> ExecuteBatchDmlAsync(ExecuteBatchDmlRequest request, CallSettings callSettings)

Executes an ExecuteBatchDml RPC asynchronously.

Parameters
Name	Description
`request`	`ExecuteBatchDmlRequest` The query request. Must not be null. The request will be modified with session and transaction details from this object. If this object's TransactionId is null, the request's transaction is not modified.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`TaskExecuteBatchDmlResponse`	A task representing the asynchronous operation. When the task completes, the result is the response from the RPC.

ExecuteSqlAsync(ExecuteSqlRequest, CallSettings)

public Task<ResultSet> ExecuteSqlAsync(ExecuteSqlRequest request, CallSettings callSettings)

Executes an ExecuteSql RPC asynchronously.

Parameters
Name	Description
`request`	`ExecuteSqlRequest` The query request. Must not be null. Will be modified to include session information from this pooled session. May be modified to include transaction and directed read options information from this pooled session and its underlying SpannerClient.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`TaskResultSet`	A task representing the asynchronous operation. When the task completes, the result is the response from the RPC.

ExecuteSqlStreamReader(ExecuteSqlRequest, CallSettings)

public ReliableStreamReader ExecuteSqlStreamReader(ExecuteSqlRequest request, CallSettings callSettings)

Creates a ReliableStreamReader for the given request.

Parameters
Name	Description
`request`	`ExecuteSqlRequest` The query request. Must not be null. Will be modified to include session information from this pooled session. May be modified to include transaction and directed read options information from this pooled session and its underlying SpannerClient.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`ReliableStreamReader`	A ReliableStreamReader for the streaming SQL request.

PartitionQueryAsync(PartitionQueryRequest, CallSettings)

public Task<PartitionResponse> PartitionQueryAsync(PartitionQueryRequest request, CallSettings callSettings)

Executes a PartitionQuery RPC asynchronously.

Parameters
Name	Description
`request`	`PartitionQueryRequest` The partitioning request. Must not be null. The request will be modified with session details from this object.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`TaskPartitionResponse`	A task representing the asynchronous operation. When the task completes, the result is the response from the RPC.

PartitionReadAsync(PartitionReadRequest, CallSettings)

public Task<PartitionResponse> PartitionReadAsync(PartitionReadRequest request, CallSettings callSettings)

Executes a PartitionRead RPC asynchronously.

Parameters
Name	Description
`request`	`PartitionReadRequest` The partitioning request. Must not be null. The request will be modified with session details from this object.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`TaskPartitionResponse`	A task representing the asynchronous operation. When the task completes, the result is the response from the RPC.

ReadStreamReader(ReadRequest, CallSettings)

public ReliableStreamReader ReadStreamReader(ReadRequest request, CallSettings callSettings)

Creates a ReliableStreamReader for the given request.

Parameters
Name	Description
`request`	`ReadRequest` The read request. Must not be null. Will be modified to include session information from this pooled session. May be modified to include transaction and directed read options information from this pooled session and its underlying SpannerClient.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`ReliableStreamReader`	A ReliableStreamReader for the streaming SQL request.

RefreshedOrNewAsync(CancellationToken)

public Task<PooledSession> RefreshedOrNewAsync(CancellationToken cancellationToken)

Always returns a new instance of PooledSession. The new instance can:

represent the same session as this one, with the same transaction options, but it won't have a transaction associated to it
represent an entirely different session with the same transaction options as this PooledSession did and no transaction associated to it If this session has expired then this method will acquire a new session in the normal way. This PooledSession instance will be disposed of to ensure that all operations with the underlying session are done through the new instance.

Parameter
Name	Description
`cancellationToken`	`CancellationToken`

Returns
Type	Description
`TaskPooledSession`

Remarks

Use this method when executing operations that are best done using the same session. For instance, when retrying aborted commits it is better if the transaction work and commit are retried with the same session, because after each abort the sessions' lock priority increments.

ReleaseToPool(bool)

public void ReleaseToPool(bool forceDelete)

Returns this session to the session pool from which it was acquired, unless it has become invalid. This method should only be called once per instance; subsequent calls are ignored. No other methods can be called after this.

Parameter
Name	Description
`forceDelete`	`bool` true to force the session to be deleted; false to allow the session to be reused.

RollbackAsync(RollbackRequest, CallSettings)

public Task RollbackAsync(RollbackRequest request, CallSettings callSettings)

Executes a Rollback RPC asynchronously.

Parameters
Name	Description
`request`	`RollbackRequest` The rollback request. Must not be null. The request will be modified with session and transaction details from this object.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`Task`	A task representing the asynchronous operation.