Class AsyncWriterConnection (2.22.0)

Version 2.22.0

• 2.25.0-rc (latest)
• 2.24.0
• 2.23.0
• 2.22.0
• 2.21.0
• 2.20.0
• 2.19.0
• 2.18.0
• 2.17.0
• 2.16.0
• 2.15.1
• 2.14.0
• 2.13.0
• 2.12.0
• 2.11.0

An interface to asynchronously perform resumable uploads.

The client library uses the google.storage.v2.StorageService.BidiWriteObject RPC to perform asynchronous resumable uploads to Google Cloud Storage. As the name implies, this is a bi-directional RPC. The messages sent via this RPC are google.storage.v2.BidiWriteObjectRequest and google.storage.v2.BidiWriteObjectResponse.

• The BidiWriteObjectRequest messages upload the object data.
• The last BidiWriteObjectRequest message in an upload must include a finalize attribute. These messages result in a BidiWriteObjectResponse message, which includes the metadata of the GCS object created by the upload.
• BidiWriteObjectRequest messages may include a flush attribute. Such messages result in a BidiReadObjectResponse message, which includes how much of the uploaded data has been persisted.
• BidiWriteObjectRequest messages may not include more than google.storage.v2.ServiceConstants.MAX_WRITE_CHUNK_BYTES bytes of payload.

In this interface different member functions write messages with different attributes.

The Write() member function uploads some data, without setting any finalize or flush attributes. If necessary, the data is broken into multiple BidiWriteObjectRequest messages.

The Finalize() member function uploads some data and sets the finalize attribute. If needed, the data is broken into multiple messages to satisfy the MAX_WRITE_CHUNK_BYTES limit. Only the last message has the finalize attribute. This function also waits for the response message and returns the object metadata (or an error).

The Flush() member function uploads some data and sets the flush attribute. As with the other functions the data may need to be broken into multiple messages. Only the last message will have the flush attribute set.

This interface can be used to mock the behavior of these bidirectional streaming RPCs. Applications may use these mocks in their own tests.

Warning: We expect most applications will use this class in mocks or via the AsyncWriter wrapper, and do not recommend its use outside mocks. If using this class directly keep in mind the following restrictions: - Never destroy an AsyncWriterConnection object while any calls to Write(), Flush(), Query(), or Finalize() are pending. - Have at most one call to Write() or Flush() pending. - Do not issue a Write() call while a Flush() call is pending or vice-versa. - Do not issue any Finalize() calls while a Write(), Flush(), or Query() call is pending. - Only issue one Finalize() call. - Issue exactly one Query() call after a Flush() call completes.

Functions

Cancel()

Cancels the streaming RPC, terminating any pending operations.

Returns
Type	Description
void

UploadId() const

Returns the upload id. Used to checkpoint the state and resume uploads.

Returns
Type	Description
std::string

PersistedState() const

Returns the last known state of the upload.

Updated during initialization and by successful Query() or Finalize() requests.

Returns
Type	Description
absl::variant< std::int64_t, storage::ObjectMetadata >

Write(WritePayload)

Uploads some data to the service.

Parameter
Name	Description
payload	WritePayload

Returns
Type	Description
future< Status >

Finalize(WritePayload)

Finalizes an upload.

Parameter
Name	Description
	WritePayload

Returns
Type	Description
future< StatusOr< storage::ObjectMetadata > >

Flush(WritePayload)

Uploads some data to the service and flushes the value.

Parameter
Name	Description
payload	WritePayload

Returns
Type	Description
future< Status >

Query()

Wait for the result of a Flush() call.

Returns
Type	Description
future< StatusOr< std::int64_t > >

GetRequestMetadata()

Return the request metadata.

Returns
Type	Description
RpcMetadata