Skip to content
This repository was archived by the owner on Sep 25, 2026. It is now read-only.

Commit cb0556d

Browse files
committed
docs(samples): add zonal bucket pre-warmed writer pool sample
Adds OptimizeWriteLatencyPool sample (region tag: storage_optimize_write_latency_pool) demonstrating a pre-warmed pool of appendable object writers with CloseAction.CLOSE_WITHOUT_FINALIZING to avoid object creation and finalization metadata overhead on the critical write path. Verified with both mock unit tests and live integration testing against a Rapid (zonal) bucket in us-central1-a: Running live Java test against bucket=<zonal-bucket>, prefix=live_java_pool_1790087142149 Java read back: "0123456789", pool size after refill: 3 Time: 3.94s OK (1 test)
1 parent 679cddd commit cb0556d

1 file changed

Lines changed: 117 additions & 0 deletions

File tree

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.example.storage.object;
18+
19+
// [START storage_optimize_write_latency_pool]
20+
21+
import com.google.cloud.storage.BlobAppendableUpload.AppendableUploadWriteableByteChannel;
22+
import com.google.cloud.storage.BlobAppendableUploadConfig;
23+
import com.google.cloud.storage.BlobAppendableUploadConfig.CloseAction;
24+
import com.google.cloud.storage.BlobId;
25+
import com.google.cloud.storage.BlobInfo;
26+
import com.google.cloud.storage.BlobReadSession;
27+
import com.google.cloud.storage.RangeSpec;
28+
import com.google.cloud.storage.ReadProjectionConfigs;
29+
import com.google.cloud.storage.Storage;
30+
import com.google.cloud.storage.StorageOptions;
31+
import java.nio.ByteBuffer;
32+
import java.nio.charset.StandardCharsets;
33+
import java.util.Queue;
34+
import java.util.concurrent.ConcurrentLinkedQueue;
35+
import java.util.concurrent.ExecutorService;
36+
import java.util.concurrent.Executors;
37+
import java.util.concurrent.Future;
38+
import java.util.concurrent.TimeUnit;
39+
40+
public class OptimizeWriteLatencyPool {
41+
public static void optimizeWriteLatencyPool(String bucketName, String keyPrefix)
42+
throws Exception {
43+
// The ID of your GCS zonal bucket
44+
// String bucketName = "your-unique-bucket-name";
45+
46+
// The prefix for your pooled GCS objects
47+
// String keyPrefix = "pooled-object";
48+
49+
int poolSize = 3;
50+
String nextObjectName = keyPrefix + "_" + poolSize;
51+
byte[] payload = "0123456789".getBytes(StandardCharsets.UTF_8);
52+
ExecutorService executor = Executors.newSingleThreadExecutor();
53+
54+
try (Storage storage = StorageOptions.grpc().build().getService()) {
55+
BlobAppendableUploadConfig config =
56+
BlobAppendableUploadConfig.of().withCloseAction(CloseAction.CLOSE_WITHOUT_FINALIZING);
57+
58+
// 1. Init pool: Sized to ensure pre-warmed channels are always available.
59+
Queue<AppendableUploadWriteableByteChannel> pool = new ConcurrentLinkedQueue<>();
60+
for (int i = 0; i < poolSize; i++) {
61+
BlobInfo info = BlobInfo.newBuilder(bucketName, keyPrefix + "_" + i).build();
62+
AppendableUploadWriteableByteChannel ch =
63+
storage
64+
.blobAppendableUpload(info, config, Storage.BlobWriteOption.doesNotExist())
65+
.open(); // Establishes stream and creates 0-byte object in the background.
66+
pool.add(ch);
67+
}
68+
69+
// 2. Write: Pop a pre-warmed writer and commit with flush() (~1-2 ms)
70+
// instead of blocking on close().
71+
AppendableUploadWriteableByteChannel channel = pool.poll();
72+
channel.write(ByteBuffer.wrap(payload));
73+
channel.flush();
74+
75+
// 3. Pool maintenance (run asynchronously off the critical write path):
76+
// Close the used channel without finalizing and refill the pool.
77+
Future<Void> maintenanceFuture =
78+
executor.submit(
79+
() -> {
80+
channel.closeWithoutFinalizing();
81+
BlobInfo nextInfo = BlobInfo.newBuilder(bucketName, nextObjectName).build();
82+
AppendableUploadWriteableByteChannel replacement =
83+
storage
84+
.blobAppendableUpload(
85+
nextInfo, config, Storage.BlobWriteOption.doesNotExist())
86+
.open();
87+
pool.add(replacement);
88+
return null;
89+
});
90+
91+
// 4. Read: Unfinalized objects are readable after flush().
92+
try (BlobReadSession readSession =
93+
storage
94+
.blobReadSession(BlobId.of(bucketName, keyPrefix + "_0"))
95+
.get(10, TimeUnit.SECONDS)) {
96+
byte[] bytes =
97+
readSession
98+
.readAs(
99+
ReadProjectionConfigs.asFutureBytes()
100+
.withRangeSpec(RangeSpec.of(0, payload.length)))
101+
.get();
102+
System.out.printf(
103+
"Read unfinalized object %s_0: %s%n",
104+
keyPrefix, new String(bytes, StandardCharsets.UTF_8));
105+
}
106+
107+
maintenanceFuture.get(10, TimeUnit.SECONDS);
108+
for (AppendableUploadWriteableByteChannel rem : pool) {
109+
rem.closeWithoutFinalizing();
110+
}
111+
} finally {
112+
executor.shutdown();
113+
}
114+
}
115+
}
116+
117+
// [END storage_optimize_write_latency_pool]

0 commit comments

Comments
 (0)