Bug 1466792 - Update out-of-date memory allocation comments r=sfink
authorJon Coppeard <jcoppeard@mozilla.com>
Wed, 06 Jun 2018 10:54:59 +0100
changeset 421582 f72ccbb154263d442b58e10a8dc69da9cd004a4d
parent 421581 072201279e41b15e1ff1606bfd7460e3656d13b3
child 421583 450557c0669f09c69dbdc2837e9ca5c24125f789
push id34098
push usernbeleuzu@mozilla.com
push dateWed, 06 Jun 2018 17:00:32 +0000
treeherdermozilla-central@04cc917f68c5 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerssfink
bugs1466792
milestone62.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1466792 - Update out-of-date memory allocation comments r=sfink
js/public/Utility.h
--- a/js/public/Utility.h
+++ b/js/public/Utility.h
@@ -433,40 +433,49 @@ static inline void js_free(void* p)
  *     error and we cannot override them not to.
  *
  * Allocation:
  *
  * - If the lifetime of the allocation is tied to the lifetime of a GC-thing
  *   (that is, finalizing the GC-thing will free the allocation), call one of
  *   the following functions:
  *
- *     JSContext::{malloc_,realloc_,calloc_,new_}
- *     JSRuntime::{malloc_,realloc_,calloc_,new_}
+ *     JSContext::{pod_malloc,pod_calloc,pod_realloc}
+ *     Zone::{pod_malloc,pod_calloc,pod_realloc}
  *
  *   These functions accumulate the number of bytes allocated which is used as
- *   part of the GC-triggering heuristic.
+ *   part of the GC-triggering heuristics.
  *
- *   The difference between the JSContext and JSRuntime versions is that the
- *   cx version reports an out-of-memory error on OOM. (This follows from the
+ *   The difference between the JSContext and Zone versions is that the
+ *   cx version report an out-of-memory error on OOM. (This follows from the
  *   general SpiderMonkey idiom that a JSContext-taking function reports its
  *   own errors.)
  *
+ *   If you don't want to report an error on failure, there are maybe_ versions
+ *   of these methods available too, e.g. maybe_pod_malloc.
+ *
+ *   The methods above use templates to allow allocating memory suitable for an
+ *   array of a given type and number of elements. There are _with_extra
+ *   versions to allow allocating an area of memory which is larger by a
+ *   specified number of bytes, e.g. pod_malloc_with_extra.
+ *
+ *   These methods are available on a JSRuntime, but calling them is
+ *   discouraged. Memory attributed to a runtime can only be reclaimed by full
+ *   GCs, and we try to avoid those where possible.
+ *
  * - Otherwise, use js_malloc/js_realloc/js_calloc/js_new
  *
  * Deallocation:
  *
  * - Ordinarily, use js_free/js_delete.
  *
  * - For deallocations during GC finalization, use one of the following
  *   operations on the FreeOp provided to the finalizer:
  *
  *     FreeOp::{free_,delete_}
- *
- *   The advantage of these operations is that the memory is batched and freed
- *   on another thread.
  */
 
 /*
  * Given a class which should provide a 'new' method, add
  * JS_DECLARE_NEW_METHODS (see js::MallocProvider for an example).
  *
  * Note: Do not add a ; at the end of a use of JS_DECLARE_NEW_METHODS,
  * or the build will break.