Allocate and free memory that is not managed by the garbage collector.
Syntax
void * JS_malloc(JSContext *cx, size_t nbytes); void * JS_realloc(JSContext *cx, void *p, size_t oldBytes, size_t newBytes); char * JS_strdup(JSContext *cx, const char *s); void JS_free(JSContext *cx, void *p);
Name | Type | Description |
---|---|---|
cx |
JSContext * |
Pointer to a JS context. If allocation fails, an error is reported in this context. |
p | void * | (JS_realloc and JS_free only) Pointer to a previously allocated region of memory to resize or deallocate. |
nbytes |
size_t |
(JS_malloc and JS_realloc only) Amount of space, in bytes, to allocate. |
s | const char * | (JS_strdup only) Pointer to a null-terminated string. s must not be NULL . |
Description
JS_malloc
allocates a region of memory nbytes
in size. On success, JS_malloc
returns a pointer to the beginning of the region. As with the standard C function malloc
, memory allocated by JS_malloc
is uninitialized.
JS_realloc
tries to change the allocation size of the region of memory at p
to nbytes
. Failing that, JS_realloc
allocates a new region of size nbytes
and copies as much of the existing data in p
as will fit to the new region. Then it frees the region at p
and returns a pointer to the new region. Apart from whatever is copied, any newly allocated space is uninitialized. JS_realloc(cx, NULL, nbytes)
behaves exactly like JS_malloc(cx, nbytes)
. When p
is not null, JS_realloc(cx, p, 0)
behaves like JS_free(cx, p)
and returns NULL
.
JS_strdup
allocates a copy of the null-terminated string s
. On success, it returns a pointer to the copy.
If any of these three functions fails to allocate the required amount of memory, it reports an error as though by calling
and returns JS_ReportOutOfMemory
(cx)NULL
.
JS_free
deallocates a region of memory allocated a previous call to JS_malloc
, JS_realloc
, or JS_strdup
. If p
is null, JS_free
does nothing. Once the region of memory is freed, the application must not use it again.
For JS_realloc
and JS_free
, if p
is non-null, cx
must be associated with the same runtime as the context used to allocate p
. That is, it is safe to allocate memory in one context and free it in another, as long as both contexts are in the same runtime.
Implementation note: Currently these four functions are implemented using the corresponding standard C functions. Do not make assumptions based on this implementation detail. Future releases may implement these functions differently.
JS_realloc
code sample
realloc
is famously tricky to use correctly. Here is an example of proper code:
/* * `p` points to the memory area to resize. * We want to resize it to `newsize` bytes. */ void *p2 = JS_realloc(cx, p, newsize); if (p2 == NULL) { if (p != NULL) JS_free(cx, p); p = NULL; return NULL; } p = p2;