Perform resumable uploads asynchronously.
Resumable uploads allow applications to continue uploading data after network disconnects and application restarts. To resume an upload the library first queries the current state of the upload. The upload uses this information to send the remaining data. Applications only need to checkpoint a string, the UploadId(), to resume an upload even after the application itself restarts.
Some data sources do not permit rewinding to an arbitrary point. For example: if the application is receiving streaming data from an external source it may be impossible to shutdown the application and recover the data streamed while the application was down.
This API does not support resuming uploading data from streaming data sources. If the upload is interrupted you must be able to start sending data from an arbitrary point.
Constructors
AsyncWriter(AsyncWriter &&)
Move-only.
| Parameter | |
|---|---|
| Name | Description |
|
AsyncWriter &&
|
AsyncWriter(AsyncWriter const &)
Move-only.
| Parameter | |
|---|---|
| Name | Description |
|
AsyncWriter const &
|
AsyncWriter()
AsyncWriter(std::unique_ptr< AsyncWriterConnection >)
| Parameter | |
|---|---|
| Name | Description |
impl |
std::unique_ptr< AsyncWriterConnection >
|
Operators
operator=(AsyncWriter &&)
Move-only.
| Parameter | |
|---|---|
| Name | Description |
|
AsyncWriter &&
|
| Returns | |
|---|---|
| Type | Description |
AsyncWriter & | |
operator=(AsyncWriter const &)
Move-only.
| Parameter | |
|---|---|
| Name | Description |
|
AsyncWriter const &
|
| Returns | |
|---|---|
| Type | Description |
AsyncWriter & | |
Functions
UploadId() const
The upload id.
Applications that need to resume uploads after a restart should checkpoint this value to persistent storage.
| Returns | |
|---|---|
| Type | Description |
std::string | |
PersistedState() const
The state of the current upload.
This returns the last "known" state of the upload. The values are updated (1) when the AsyncWriter object is created, and (2) on calls to Query() and Finalize().
Applications may finalize an upload, and then try to resume the upload. In this case this function returns storage::ObjectMetadata.
During an upload the service will periodically persist the uploaded data. Applications should not assume that all data "sent" is persisted. The service may buffer the data in ephemeral storage before persisting it.
If the application needs to resume an upload that was interrupted, then it must check PersistedState() before sending data. The service will assume that new data starts at the correct offset.
If an upload is resumed after it is finalized, the library will return a variant holding storage::ObjectMetadata value.
Otherwise the variant returns the size of the persisted data. The application should send the remaining data to upload, starting from this point.
| Returns | |
|---|---|
| Type | Description |
absl::variant< std::int64_t, storage::ObjectMetadata > | |
Write(AsyncToken, WritePayload)
Upload payload returning a new token to continue the upload.
| Parameters | |
|---|---|
| Name | Description |
token |
AsyncToken
|
payload |
WritePayload
|
| Returns | |
|---|---|
| Type | Description |
future< StatusOr< AsyncToken > > | |
Finalize(AsyncToken)
Finalize the upload with the existing data.
| Parameter | |
|---|---|
| Name | Description |
token |
AsyncToken
|
| Returns | |
|---|---|
| Type | Description |
future< StatusOr< storage::ObjectMetadata > > | |
Finalize(AsyncToken, WritePayload)
Upload payload and then finalize the upload.
| Parameters | |
|---|---|
| Name | Description |
token |
AsyncToken
|
payload |
WritePayload
|
| Returns | |
|---|---|
| Type | Description |
future< StatusOr< storage::ObjectMetadata > > | |
GetRequestMetadata() const
The headers (if any) returned by the service.
For debugging only.
| Returns | |
|---|---|
| Type | Description |
RpcMetadata | |