feat(c-sdk): optional version/size fast-path and concurrent block reads (#564)

talon_read_async gains a version (const char*) and object_size
(const uint64_t*) parameter pair, each independently nullable. NULL means
the caller does not have that value. The read skips the StatObject control
round trip only when BOTH are non-NULL, using the caller-supplied version
and size; if either is NULL the SDK resolves both with a stat and ignores
any lone value, since a read cannot skip the stat without both halves.

Making object_size a pointer lets a caller that has a version but no valid
size say so (NULL) instead of guessing, and disambiguates a real empty
object (points to 0 -> zero-byte read, no stat) from "unknown" (NULL).
When used, *object_size bounds the read at EOF: smaller than the range is
a POSIX short read, larger surfaces as a clear worker error rather than
fabricated bytes.

The per-block fetches a multi-block read spans now run concurrently on the
runtime (JoinSet over disjoint 'static sub-slices of the caller buffer)
instead of a serial await loop, so a large read no longer pays one worker
RTT per block in series.

Header, smoke test, example, and the MinIO e2e are updated to the new
signature; the e2e also adds a fast-path case that reuses the version and
size from its stat.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: somfornot

clients/c/examples/async_read.c

@@ -47,12 +47,15 @@ int main(void) {
     pthread_cond_init(&ctx->cond, NULL);
 
     uint64_t request_id = 0;
+    /* version = NULL, object_size = NULL → the SDK resolves both with a stat. */
     int status = talon_read_async(
         client,
         "s3://bucket/path/object.bin",
         0,
         ctx->buffer,
         4096,
+        NULL,
+        NULL,
         on_read,
         ctx,
         &request_id);

clients/c/include/talon.h

@@ -67,13 +67,30 @@ void talon_client_free(talon_client *client);
  * [dst, dst + dst_len) is exclusively owned by the SDK until the callback runs:
  * callers must not read, write, free, or reuse overlapping storage for another
  * operation during that interval. A zero-length read may pass NULL for dst.
+ *
+ * version and object_size are each optional and independently nullable; NULL
+ * means the caller does not have that value. The read skips the StatObject round
+ * trip only when BOTH are non-NULL, using the caller-supplied version and size
+ * (the caller owns keeping them current for the object generation being read).
+ * If either is NULL the SDK resolves both with a StatObject first and any lone
+ * value supplied is ignored, since a read cannot skip the stat without both.
+ *
+ * When used, *object_size is the object's total byte length and bounds the read
+ * at EOF (a POSIX short read): a value smaller than offset + dst_len yields a
+ * short read, 0 denotes a genuinely empty object (an unambiguous zero-byte
+ * read), and a value larger than the object surfaces as a read error rather than
+ * fabricated bytes. A caller with no valid size passes NULL.
+ *
+ * Blocks spanned by the read are fetched concurrently.
  */
 int talon_read_async(
     talon_client *client,
     const char *uri,
     uint64_t offset,
     uint8_t *dst,
     size_t dst_len,
+    const char *version,
+    const uint64_t *object_size,
     talon_callback callback,
     void *user_data,
     uint64_t *request_id_out);