From 56d75f2747bc2f2aec0340b18cbc9d668fc84fc0 Mon Sep 17 00:00:00 2001 From: "dmichael@chromium.org" Date: Thu, 10 Apr 2014 23:58:41 +0000 Subject: PPAPI: Update pp_var.h documentation for Resource vars. BUG=361215 R=raymes@chromium.org Review URL: https://codereview.chromium.org/229033003 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@263135 0039d316-1c4b-4281-b951-d872f2087c98 --- ppapi/api/pp_var.idl | 31 +++++++++++++++++++++---------- ppapi/api/ppb_var.idl | 20 +++++++++++++------- ppapi/c/pp_var.h | 33 ++++++++++++++++++++++----------- ppapi/c/ppb_var.h | 20 +++++++++++++------- 4 files changed, 69 insertions(+), 35 deletions(-) diff --git a/ppapi/api/pp_var.idl b/ppapi/api/pp_var.idl index 425d99b..545585d 100644 --- a/ppapi/api/pp_var.idl +++ b/ppapi/api/pp_var.idl @@ -45,15 +45,15 @@ enum PP_VarType { * The Var represents a string. The as_id field is used to * identify the string, which may be created and retrieved from the * PPB_Var interface. These objects are reference counted, so - * AddRef and Release must be used properly to avoid memory leaks. + * AddRef() and Release() must be used properly to avoid memory leaks. */ PP_VARTYPE_STRING = 5, /** * Represents a JavaScript object. This vartype is not currently usable * from modules, although it is used internally for some tasks. These objects - * are reference counted, so AddRef and Release must be used properly to avoid - * memory leaks. + * are reference counted, so AddRef() and Release() must be used properly to + * avoid memory leaks. */ PP_VARTYPE_OBJECT = 6, @@ -61,7 +61,7 @@ enum PP_VarType { * Represents an array of Vars. The as_id field is used to * identify the array, which may be created and manipulated from the * PPB_VarArray interface. These objects are reference counted, - * so AddRef and Release must be used properly to avoid memory leaks. + * so AddRef() and Release() must be used properly to avoid memory leaks. */ PP_VARTYPE_ARRAY = 7, @@ -69,7 +69,8 @@ enum PP_VarType { * Represents a mapping from strings to Vars. The as_id field is * used to identify the dictionary, which may be created and manipulated from * the PPB_VarDictionary interface. These objects are reference - * counted, so AddRef and Release must be used properly to avoid memory leaks. + * counted, so AddRef() and Release() must be used properly to avoid memory + * leaks. */ PP_VARTYPE_DICTIONARY = 8, @@ -78,15 +79,25 @@ enum PP_VarType { * represents Typed Arrays in JavaScript. Unlike JavaScript 'Array', it is * only meant to contain basic numeric types, and is always stored * contiguously. See PPB_VarArrayBuffer_Dev for functions special to - * ArrayBuffer vars. These objects are reference counted, so AddRef and - * Release must be used properly to avoid memory leaks. + * ArrayBuffer vars. These objects are reference counted, so AddRef() and + * Release() must be used properly to avoid memory leaks. */ PP_VARTYPE_ARRAY_BUFFER = 9, /** - * Resources are not currently supported but will be added in the future - * These objects are reference counted, so AddRef and Release must be used - * properly to avoid memory leaks. + * This type allows the PP_Var to wrap a PP_Resource + * . This can be useful for sending or receiving some types of + * PP_Resource using PPB_Messaging or + * PPP_Messaging. + * + * These objects are reference counted, so AddRef() and Release() must be used + * properly to avoid memory leaks. Under normal circumstances, the + * PP_Var will implicitly hold a reference count on the + * PP_Resource on your behalf. For example, if you call + * VarFromResource(), it implicitly calls PPB_Core::AddRefResource() on the + * PP_Resource. Likewise, PPB_Var::Release() on a Resource + * PP_Var will invoke PPB_Core::ReleaseResource() when the Var + * reference count goes to zero. */ PP_VARTYPE_RESOURCE = 10 }; diff --git a/ppapi/api/ppb_var.idl b/ppapi/api/ppb_var.idl index ecb3707..cc12b1b 100644 --- a/ppapi/api/ppb_var.idl +++ b/ppapi/api/ppb_var.idl @@ -29,9 +29,13 @@ interface PPB_Var { /** * Release() removes a reference to given var, deleting it if the internal - * reference count becomes 0. If the given var is not a refcounted object, - * this function will do nothing so you can always call it no matter what - * the type. + * reference count becomes 0. If the PP_Var is of type + * PP_VARTYPE_RESOURCE, + * it will implicitly release a reference count on the + * PP_Resource (equivalent to PPB_Core::ReleaseResource()). + * + * If the given var is not a refcounted object, this function will do nothing + * so you can always call it no matter what the type. * * @param[in] var A PP_Var that will have a reference removed. */ @@ -46,7 +50,7 @@ interface PPB_Var { * * If the length is 0, the *data pointer will not be dereferenced * and may be NULL. Note, however if length is 0, the - * "NULL-ness" will not be preserved, as VarToUtf8 will never + * "NULL-ness" will not be preserved, as VarToUtf8() will never * return NULL on success, even for empty strings. * * The resulting object will be a refcounted string object. It will be @@ -74,8 +78,8 @@ interface PPB_Var { * * If the length is 0, the *data pointer will not be dereferenced * and may be NULL. Note, however if length is 0, the - * "NULL-ness" will not be preserved, as VarToUtf8 will never - * return NULL on success, even for empty strings. + * "NULL-ness" will not be preserved, as VarToUtf8() will never return + * NULL on success, even for empty strings. * * The resulting object will be a refcounted string object. It will be * AddRef'ed for the caller. When the caller is done with it, it should be @@ -127,7 +131,9 @@ interface PPB_Var { PP_Resource VarToResource([in] PP_Var var); /** - * Creates a new PP_Var from a given resource. + * Creates a new PP_Var from a given resource. Implicitly adds a + * reference count on the PP_Resource (equivalent to + * PPB_Core::AddRefResource(resource)). * * @param[in] resource A PP_Resource to be wrapped in a var. * diff --git a/ppapi/c/pp_var.h b/ppapi/c/pp_var.h index 0648c65..15a8df6 100644 --- a/ppapi/c/pp_var.h +++ b/ppapi/c/pp_var.h @@ -3,7 +3,7 @@ * found in the LICENSE file. */ -/* From pp_var.idl modified Thu Sep 12 16:41:36 2013. */ +/* From pp_var.idl modified Thu Apr 10 14:52:30 2014. */ #ifndef PPAPI_C_PP_VAR_H_ #define PPAPI_C_PP_VAR_H_ @@ -54,28 +54,29 @@ typedef enum { * The Var represents a string. The as_id field is used to * identify the string, which may be created and retrieved from the * PPB_Var interface. These objects are reference counted, so - * AddRef and Release must be used properly to avoid memory leaks. + * AddRef() and Release() must be used properly to avoid memory leaks. */ PP_VARTYPE_STRING = 5, /** * Represents a JavaScript object. This vartype is not currently usable * from modules, although it is used internally for some tasks. These objects - * are reference counted, so AddRef and Release must be used properly to avoid - * memory leaks. + * are reference counted, so AddRef() and Release() must be used properly to + * avoid memory leaks. */ PP_VARTYPE_OBJECT = 6, /** * Represents an array of Vars. The as_id field is used to * identify the array, which may be created and manipulated from the * PPB_VarArray interface. These objects are reference counted, - * so AddRef and Release must be used properly to avoid memory leaks. + * so AddRef() and Release() must be used properly to avoid memory leaks. */ PP_VARTYPE_ARRAY = 7, /** * Represents a mapping from strings to Vars. The as_id field is * used to identify the dictionary, which may be created and manipulated from * the PPB_VarDictionary interface. These objects are reference - * counted, so AddRef and Release must be used properly to avoid memory leaks. + * counted, so AddRef() and Release() must be used properly to avoid memory + * leaks. */ PP_VARTYPE_DICTIONARY = 8, /** @@ -83,14 +84,24 @@ typedef enum { * represents Typed Arrays in JavaScript. Unlike JavaScript 'Array', it is * only meant to contain basic numeric types, and is always stored * contiguously. See PPB_VarArrayBuffer_Dev for functions special to - * ArrayBuffer vars. These objects are reference counted, so AddRef and - * Release must be used properly to avoid memory leaks. + * ArrayBuffer vars. These objects are reference counted, so AddRef() and + * Release() must be used properly to avoid memory leaks. */ PP_VARTYPE_ARRAY_BUFFER = 9, /** - * Resources are not currently supported but will be added in the future - * These objects are reference counted, so AddRef and Release must be used - * properly to avoid memory leaks. + * This type allows the PP_Var to wrap a PP_Resource + * . This can be useful for sending or receiving some types of + * PP_Resource using PPB_Messaging or + * PPP_Messaging. + * + * These objects are reference counted, so AddRef() and Release() must be used + * properly to avoid memory leaks. Under normal circumstances, the + * PP_Var will implicitly hold a reference count on the + * PP_Resource on your behalf. For example, if you call + * VarFromResource(), it implicitly calls PPB_Core::AddRefResource() on the + * PP_Resource. Likewise, PPB_Var::Release() on a Resource + * PP_Var will invoke PPB_Core::ReleaseResource() when the Var + * reference count goes to zero. */ PP_VARTYPE_RESOURCE = 10 } PP_VarType; diff --git a/ppapi/c/ppb_var.h b/ppapi/c/ppb_var.h index 91a6592..b4a361a 100644 --- a/ppapi/c/ppb_var.h +++ b/ppapi/c/ppb_var.h @@ -3,7 +3,7 @@ * found in the LICENSE file. */ -/* From ppb_var.idl modified Thu Feb 6 13:48:33 2014. */ +/* From ppb_var.idl modified Thu Apr 10 14:54:41 2014. */ #ifndef PPAPI_C_PPB_VAR_H_ #define PPAPI_C_PPB_VAR_H_ @@ -44,9 +44,13 @@ struct PPB_Var_1_2 { void (*AddRef)(struct PP_Var var); /** * Release() removes a reference to given var, deleting it if the internal - * reference count becomes 0. If the given var is not a refcounted object, - * this function will do nothing so you can always call it no matter what - * the type. + * reference count becomes 0. If the PP_Var is of type + * PP_VARTYPE_RESOURCE, + * it will implicitly release a reference count on the + * PP_Resource (equivalent to PPB_Core::ReleaseResource()). + * + * If the given var is not a refcounted object, this function will do nothing + * so you can always call it no matter what the type. * * @param[in] var A PP_Var that will have a reference removed. */ @@ -59,8 +63,8 @@ struct PPB_Var_1_2 { * * If the length is 0, the *data pointer will not be dereferenced * and may be NULL. Note, however if length is 0, the - * "NULL-ness" will not be preserved, as VarToUtf8 will never - * return NULL on success, even for empty strings. + * "NULL-ness" will not be preserved, as VarToUtf8() will never return + * NULL on success, even for empty strings. * * The resulting object will be a refcounted string object. It will be * AddRef'ed for the caller. When the caller is done with it, it should be @@ -106,7 +110,9 @@ struct PPB_Var_1_2 { */ PP_Resource (*VarToResource)(struct PP_Var var); /** - * Creates a new PP_Var from a given resource. + * Creates a new PP_Var from a given resource. Implicitly adds a + * reference count on the PP_Resource (equivalent to + * PPB_Core::AddRefResource(resource)). * * @param[in] resource A PP_Resource to be wrapped in a var. * -- cgit v1.1