summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJose Bollo <jose.bollo@iot.bzh>2019-02-25 11:27:48 +0100
committerJosé Bollo <jose.bollo@iot.bzh>2019-04-25 07:08:09 +0000
commit5214323d82cc09b15c25e348707f2639977ea763 (patch)
tree34254e72d126f0f238cbc366320e5738dcbf6a75
parent6401efb14339925e696a65eea8e8548f1fddf3ba (diff)
doc: Improve comment on asynchronous calls
Following the remarks of fellow developers, the status of the object received by the callback function needs to be explained better. Change-Id: I0e6bcd51849bbc5af92af08675949a901bfd683e Signed-off-by: Jose Bollo <jose.bollo@iot.bzh>
-rw-r--r--docs/reference-v3/func-api.md3
-rw-r--r--docs/reference-v3/func-req.md3
-rw-r--r--include/afb/afb-api-x3.h4
-rw-r--r--include/afb/afb-req-x2.h3
4 files changed, 12 insertions, 1 deletions
diff --git a/docs/reference-v3/func-api.md b/docs/reference-v3/func-api.md
index aa28932a..454bc0f6 100644
--- a/docs/reference-v3/func-api.md
+++ b/docs/reference-v3/func-api.md
@@ -293,6 +293,9 @@ struct json_object *afb_api_settings(
* 4. 'info' a string handling some info (can be NULL)
* 5. 'api' the api
*
+ * NOTE: For convenience, *json_object_put* is called on 'object' after the
+ * callback returns. So, it is wrong to call *json_object_put* in the callback.
+ *
* @param api The api that makes the call
* @param apiname The api name of the method to call
* @param verb The verb name of the method to call
diff --git a/docs/reference-v3/func-req.md b/docs/reference-v3/func-req.md
index 25644056..a91508dc 100644
--- a/docs/reference-v3/func-req.md
+++ b/docs/reference-v3/func-req.md
@@ -436,6 +436,9 @@ void afb_req_reply_f(
* 4. 'info' a string handling some info (can be NULL)
* 5. 'req' the req
*
+ * NOTE: For convenience, *json_object_put* is called on 'object' after the
+ * callback returns. So, it is wrong to call *json_object_put* in the callback.
+ *
* @param req The request
* @param api The api name of the method to call
* @param verb The verb name of the method to call
diff --git a/include/afb/afb-api-x3.h b/include/afb/afb-api-x3.h
index fc72d070..ca92bb59 100644
--- a/include/afb/afb-api-x3.h
+++ b/include/afb/afb-api-x3.h
@@ -814,6 +814,9 @@ int afb_api_x3_event_handler_del(
* 4. 'info' a string handling some info (can be NULL)
* 5. 'api' the api
*
+ * NOTE: For convenience, *json_object_put* is called on 'object' after the
+ * callback returns. So, it is wrong to call *json_object_put* in the callback.
+ *
* @param api The api that makes the call
* @param apiname The api name of the method to call
* @param verb The verb name of the method to call
@@ -821,7 +824,6 @@ int afb_api_x3_event_handler_del(
* @param callback The to call on completion
* @param closure The closure to pass to the callback
*
- *
* @see afb_req_subcall
* @see afb_req_subcall_sync
* @see afb_api_x3_call_sync
diff --git a/include/afb/afb-req-x2.h b/include/afb/afb-req-x2.h
index 9695ef60..5111f2f0 100644
--- a/include/afb/afb-req-x2.h
+++ b/include/afb/afb-req-x2.h
@@ -739,6 +739,9 @@ struct json_object *afb_req_x2_get_client_info(
* 4. 'info' a string handling some info (can be NULL)
* 5. 'req' the req
*
+ * NOTE: For convenience, *json_object_put* is called on 'object' after the
+ * callback returns. So, it is wrong to call *json_object_put* in the callback.
+ *
* @param req The request
* @param api The api name of the method to call
* @param verb The verb name of the method to call