acquire() and release() functions return pointers, for better ergonomics

include/aws/s3/s3_client.h

@@ -453,11 +453,23 @@ struct aws_s3_client *aws_s3_client_new(
     struct aws_allocator *allocator,
     const struct aws_s3_client_config *client_config);
 
+/**
+ * Add a reference, keeping this object alive.
+ * The reference must be released when you are done with it, or it's memory will never be cleaned up.
+ * You must not pass in NULL.
+ * Always returns the same pointer that was passed in.
+ */
 AWS_S3_API
-void aws_s3_client_acquire(struct aws_s3_client *client);
+struct aws_s3_client *aws_s3_client_acquire(struct aws_s3_client *client);
 
+/**
+ * Release a reference.
+ * When the reference count drops to 0, this object will be cleaned up.
+ * It's OK to pass in NULL (nothing happens).
+ * Always returns NULL.
+ */
 AWS_S3_API
-void aws_s3_client_release(struct aws_s3_client *client);
+struct aws_s3_client *aws_s3_client_release(struct aws_s3_client *client);
 
 AWS_S3_API
 struct aws_s3_meta_request *aws_s3_client_make_meta_request(
@@ -505,11 +517,23 @@ void aws_s3_meta_request_cancel(struct aws_s3_meta_request *meta_request);
 AWS_S3_API
 int aws_s3_meta_request_pause(struct aws_s3_meta_request *meta_request, struct aws_string **out_resume_token);
 
+/**
+ * Add a reference, keeping this object alive.
+ * The reference must be released when you are done with it, or it's memory will never be cleaned up.
+ * You must not pass in NULL.
+ * Always returns the same pointer that was passed in.
+ */
 AWS_S3_API
-void aws_s3_meta_request_acquire(struct aws_s3_meta_request *meta_request);
+struct aws_s3_meta_request *aws_s3_meta_request_acquire(struct aws_s3_meta_request *meta_request);
 
+/**
+ * Release a reference.
+ * When the reference count drops to 0, this object will be cleaned up.
+ * It's OK to pass in NULL (nothing happens).
+ * Always returns NULL.
+ */
 AWS_S3_API
-void aws_s3_meta_request_release(struct aws_s3_meta_request *meta_request);
+struct aws_s3_meta_request *aws_s3_meta_request_release(struct aws_s3_meta_request *meta_request);
 
 AWS_S3_API
 void aws_s3_init_default_signing_config(

source/s3_client.c

@@ -476,18 +476,19 @@ struct aws_s3_client *aws_s3_client_new(
     return NULL;
 }
 
-void aws_s3_client_acquire(struct aws_s3_client *client) {
+struct aws_s3_client *aws_s3_client_acquire(struct aws_s3_client *client) {
     AWS_PRECONDITION(client);
 
     aws_ref_count_acquire(&client->ref_count);
+    return client;
 }
 
-void aws_s3_client_release(struct aws_s3_client *client) {
-    if (client == NULL) {
-        return;
+struct aws_s3_client *aws_s3_client_release(struct aws_s3_client *client) {
+    if (client != NULL) {
+        aws_ref_count_release(&client->ref_count);
     }
 
-    aws_ref_count_release(&client->ref_count);
+    return NULL;
 }
 
 static void s_s3_client_start_destroy(void *user_data) {
@@ -830,8 +831,7 @@ struct aws_s3_meta_request *aws_s3_client_make_meta_request(
             aws_last_error(),
             aws_error_str(aws_last_error()));
 
-        aws_s3_meta_request_release(meta_request);
-        meta_request = NULL;
+        meta_request = aws_s3_meta_request_release(meta_request);
     } else {
         AWS_LOGF_INFO(AWS_LS_S3_CLIENT, "id=%p: Created meta request %p", (void *)client, (void *)meta_request);
     }
@@ -1165,8 +1165,7 @@ static void s_s3_client_process_work_default(struct aws_s3_client *client) {
 
             meta_request->client_process_work_threaded_data.scheduled = true;
         } else {
-            aws_s3_meta_request_release(meta_request);
-            meta_request = NULL;
+            meta_request = aws_s3_meta_request_release(meta_request);
         }
 
         aws_mem_release(client->allocator, meta_request_work);

source/s3_meta_request.c

@@ -368,18 +368,19 @@ bool aws_s3_meta_request_has_finish_result_synced(struct aws_s3_meta_request *me
     return true;
 }
 
-void aws_s3_meta_request_acquire(struct aws_s3_meta_request *meta_request) {
+struct aws_s3_meta_request *aws_s3_meta_request_acquire(struct aws_s3_meta_request *meta_request) {
     AWS_PRECONDITION(meta_request);
 
     aws_ref_count_acquire(&meta_request->ref_count);
+    return meta_request;
 }
 
-void aws_s3_meta_request_release(struct aws_s3_meta_request *meta_request) {
-    if (meta_request == NULL) {
-        return;
+struct aws_s3_meta_request *aws_s3_meta_request_release(struct aws_s3_meta_request *meta_request) {
+    if (meta_request != NULL) {
+        aws_ref_count_release(&meta_request->ref_count);
     }
 
-    aws_ref_count_release(&meta_request->ref_count);
+    return NULL;
 }
 
 static void s_s3_meta_request_destroy(void *user_data) {
@@ -402,7 +403,7 @@ static void s_s3_meta_request_destroy(void *user_data) {
     /* endpoint should have already been released and set NULL by the meta request finish call.
      * But call release() again, just in case we're tearing down a half-initialized meta request */
     aws_s3_endpoint_release(meta_request->endpoint);
-    aws_s3_client_release(meta_request->client);
+    meta_request->client = aws_s3_client_release(meta_request->client);
 
     AWS_ASSERT(aws_priority_queue_size(&meta_request->synced_data.pending_body_streaming_requests) == 0);
     aws_priority_queue_clean_up(&meta_request->synced_data.pending_body_streaming_requests);
@@ -481,14 +482,12 @@ static void s_s3_prepare_request_payload_callback_and_destroy(
     struct aws_s3_meta_request *meta_request = payload->request->meta_request;
     AWS_PRECONDITION(meta_request);
 
-    struct aws_s3_client *client = meta_request->client;
-    AWS_PRECONDITION(client);
+    AWS_PRECONDITION(meta_request->client);
+    struct aws_s3_client *client = aws_s3_client_acquire(meta_request->client);
 
     struct aws_allocator *allocator = client->allocator;
     AWS_PRECONDITION(allocator);
 
-    aws_s3_client_acquire(client);
-
     if (payload->callback != NULL) {
         payload->callback(meta_request, payload->request, error_code, payload->user_data);
     }

source/s3_paginator.c

@@ -120,15 +120,14 @@ struct aws_s3_paginator *aws_s3_initiate_paginator(
 
     struct aws_s3_paginator *paginator = aws_mem_calloc(allocator, 1, sizeof(struct aws_s3_paginator));
     paginator->allocator = allocator;
-    paginator->client = params->client;
+    paginator->client = aws_s3_client_acquire(params->client);
     paginator->operation = params->operation;
     paginator->on_page_finished = params->on_page_finished_fn;
     paginator->user_data = params->user_data;
 
     paginator->bucket_name = aws_string_new_from_cursor(allocator, &params->bucket_name);
     paginator->endpoint = aws_string_new_from_cursor(allocator, &params->endpoint);
 
-    aws_s3_client_acquire(params->client);
     aws_s3_paginated_operation_acquire(params->operation);
 
     aws_byte_buf_init(&paginator->result_body, allocator, s_dynamic_body_initial_buf_size);

source/s3_request.c

@@ -18,8 +18,7 @@ struct aws_s3_request *aws_s3_request_new(
     aws_ref_count_init(&request->ref_count, request, (aws_simple_completion_callback *)s_s3_request_destroy);
 
     request->allocator = meta_request->allocator;
-    request->meta_request = meta_request;
-    aws_s3_meta_request_acquire(meta_request);
+    request->meta_request = aws_s3_meta_request_acquire(meta_request);
 
     request->request_tag = request_tag;
     request->part_number = part_number;