Improve ref count semantics on http message (#359)

* Improve ref count semantics on http message

* Document the changes

Author: bretambrose

include/aws/http/request_response.h

@@ -615,16 +615,21 @@ struct aws_http_message *aws_http2_message_new_response(struct aws_allocator *al
 /**
  * Acquire a hold on the object, preventing it from being deleted until
  * aws_http_message_release() is called by all those with a hold on it.
+ *
+ * This function returns the passed in message (possibly NULL) so that acquire-and-assign can be done with a single
+ * statement.
  */
 AWS_HTTP_API
-void aws_http_message_acquire(struct aws_http_message *message);
+struct aws_http_message *aws_http_message_acquire(struct aws_http_message *message);
 
 /**
  * Release a hold on the object.
  * The object is deleted when all holds on it are released.
+ *
+ * This function always returns NULL so that release-and-assign-NULL can be done with a single statement.
  */
 AWS_HTTP_API
-void aws_http_message_release(struct aws_http_message *message);
+struct aws_http_message *aws_http_message_release(struct aws_http_message *message);
 
 /**
  * Deprecated. This is equivalent to aws_http_message_release().

source/request_response.c

@@ -537,11 +537,11 @@ void aws_http_message_destroy(struct aws_http_message *message) {
     aws_http_message_release(message);
 }
 
-void aws_http_message_release(struct aws_http_message *message) {
+struct aws_http_message *aws_http_message_release(struct aws_http_message *message) {
     /* Note that release() may also be used by new() functions to clean up if something goes wrong */
     AWS_PRECONDITION(!message || message->allocator);
     if (!message) {
-        return;
+        return NULL;
     }
 
     size_t prev_refcount = aws_atomic_fetch_sub(&message->refcount, 1);
@@ -557,11 +557,16 @@ void aws_http_message_release(struct aws_http_message *message) {
     } else {
         AWS_ASSERT(prev_refcount != 0);
     }
+
+    return NULL;
 }
 
-void aws_http_message_acquire(struct aws_http_message *message) {
-    AWS_PRECONDITION(message);
-    aws_atomic_fetch_add(&message->refcount, 1);
+struct aws_http_message *aws_http_message_acquire(struct aws_http_message *message) {
+    if (message != NULL) {
+        aws_atomic_fetch_add(&message->refcount, 1);
+    }
+
+    return message;
 }
 
 bool aws_http_message_is_request(const struct aws_http_message *message) {