JS_SetPrivate

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.finalize callback.
  • If your class's private data contains any jsvals or other references to JavaScript objects, implement the JSClass.mark callback 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.

See Also