Skip to content

docs: update BlobAppendableUpload.AppendableUploadWriteableByteChannel to indicate it is non-blocking #3235

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

docs: update BlobAppendableUpload.AppendableUploadWriteableByteChannel to indicate it is non-blocking #3235

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions google-cloud-storage/clirr-ignored-differences.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,5 +177,11 @@
<className>com/google/cloud/storage/FlushPolicy$MaxFlushSizeFlushPolicy</className>
<method>FlushPolicy$MaxFlushSizeFlushPolicy(int)</method>
</difference>
<!-- this method is already on the parent interface, and is on an @InternalExtensionOnly interface -->
<difference>
<differenceType>7012</differenceType>
<className>com/google/cloud/storage/BlobAppendableUpload$AppendableUploadWriteableByteChannel</className>
<method>int write(java.nio.ByteBuffer)</method>
</difference>

</differences>
38 changes: 34 additions & 4 deletions google-cloud-storage/src/main/java/com/google/cloud/storage/BlobAppendableUpload.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
import com.google.cloud.storage.Storage.BlobWriteOption;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.channels.ClosedChannelException;
import java.nio.channels.WritableByteChannel;
import java.util.concurrent.TimeUnit;

Expand Down Expand Up @@ -90,14 +91,38 @@ public interface BlobAppendableUpload extends BlobWriteSession {
* <p>This interface allows writing bytes to an Appendable Upload, and provides methods to close
* this channel -- optionally finalizing the upload.
*
* <p>The {@link #write(ByteBuffer)} method of this channel is non-blocking.
*
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
@InternalExtensionOnly
interface AppendableUploadWriteableByteChannel extends WritableByteChannel {

/**
* Finalize the upload and close this instance to further {@link #write(ByteBuffer)}ing. This
* <b>This method is non-blocking</b>
*
* <p>Consume as many bytes as can fit in the underlying outbound queue. The size of the
* outbound queue is determined from {@link BlobAppendableUploadConfig#getFlushPolicy()}{@code
* .}{@link FlushPolicy#getMaxPendingBytes() getMaxPendingBytes()}. If the outbound queue is
* full, and can not fit more bytes, this method will return 0.
*
* <p>This method may be invoked at any time. If another thread has already initiated a write
* operation upon this channel, however, then an invocation of this method will block until the
* first operation is complete.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems contradictory with the first claim? Unless we don't consider that blocking because the first call is simply doing a memory copy?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll remove that. We can make the lock acquisition conditional too and return 0 if we can't acquire the lock.

*
* @param src The buffer from which bytes are to be retrieved
* @return The number of bytes written, possibly zero
* @throws ClosedChannelException If this channel is closed
* @throws IOException If some other I/O error occurs
*/
@Override
int write(ByteBuffer src) throws IOException;

/**
* <b>This method is blocking</b>
*
* <p>Finalize the upload and close this instance to further {@link #write(ByteBuffer)}ing. This
* will close any underlying stream and release any releasable resources once out of scope.
*
* <p>Once this method is called, and returns no more writes to the object will be allowed by
Expand All @@ -116,8 +141,11 @@ interface AppendableUploadWriteableByteChannel extends WritableByteChannel {
void finalizeAndClose() throws IOException;

/**
* Close this instance to further {@link #write(ByteBuffer)}ing without finalizing the upload.
* This will close any underlying stream and release any releasable resources once out of scope.
* <b>This method is blocking</b>
*
* <p>Close this instance to further {@link #write(ByteBuffer)}ing without finalizing the
* upload. This will close any underlying stream and release any releasable resources once out
* of scope.
*
* <p>This method, {@link AppendableUploadWriteableByteChannel#finalizeAndClose()} and {@link
* AppendableUploadWriteableByteChannel#close()} are mutually exclusive. If one of the other
Expand All @@ -133,7 +161,9 @@ interface AppendableUploadWriteableByteChannel extends WritableByteChannel {
void closeWithoutFinalizing() throws IOException;

/**
* Close this instance to further {@link #write(ByteBuffer)}ing.
* <b>This method is blocking</b>
*
* <p>Close this instance to further {@link #write(ByteBuffer)}ing.
*
* <p>Whether the upload is finalized during this depends on the {@link
* BlobAppendableUploadConfig#getCloseAction()} provided to create the {@link
Expand Down
Loading