Sets the private data field of an object.
Syntax
void JS_SetPrivate(JSObject *obj, void *data);
| Name | Type | Description |
|---|---|---|
obj |
JSObject * |
Object for which to set private data. |
data |
void * |
Private data for the object. This pointer must be aligned to a 2-byte boundary. |
Description
If a JSClass has the JSCLASS_HAS_PRIVATE flag, each object of that class has a private field of type void * which the application may use for any purpose. It is especially useful for storing C/C++ data that should not be directly visible to scripts. For example, a Socket class might use the private data field to store the socket handle.
JS_SetPrivate sets an object's private data field. obj must be an instance of a class that has the JSCLASS_HAS_PRIVATE flag.
Only the pointer is stored. Memory management of this field is the application's responsibility. The JavaScript engine never uses it. In particular:
- If you allocate memory for private data, you must free it, typically in a
JSClass.finalizecallback. - If your class's private data contains any
jsvals or other references to JavaScript objects, implement theJSClass.markcallback to ensure they are not prematurely reclaimed by the garbage collector.
Use JS_GetInstancePrivate to safely extract the private data from an object. (See the warning at JS_GetPrivate.)
Never use JS_SetPrivate on an instance of a class you don't own. That object may already be using the private data field for something else; or there might not be a private data field in that object at all, in which case JS_SetPrivate would overwrite an object property. This could lead to a crash or worse.