duktape/website/api/duk_compact.yaml

name: duk_compact

proto: |
  void duk_compact(duk_context *ctx, duk_idx_t obj_idx);

summary: |
  <p>
  Resizes an object's internal memory allocation to minimize memory usage.
  If the value at <code>obj_idx</code> is not an object, does nothing.
  Although compaction is normally safe, it can fail due to an internal error
  (such as out-of-memory error).  Compaction only affects to an object's
  "own properties", not its inherited properties.
  </p>

  <p>
  Compaction is not a final operation and has no impact on object semantics.
  Adding new properties to the object is still possible (assuming the object
  is extensible), but causes an object resize.  Existing property values can be
  changed (assuming the properties are writable) without affecting the object's
  internal memory allocation.  An object can be compacted multiple times:
  for instance, if a new property is added to a previously compacted object,
  the object can be compacted again to minimize memory footprint after the
  property addition.
  </p>

  <p>
  Compacting an object saves a small amount of memory per object.  It is
  generally useful when (1) memory footprint is very important, (2) an object
  is unlikely to gain new properties, (3) an object is relatively long-lived,
  and (4) when compaction can be applied to enough many objects to make a
  significant difference.
  </p>

  <p>
  If <code>Object.seal()</code>, <code>Object.freeze()</code>, or
  <code>Object.preventExtensions()</code> is called, an object is automatically
  compacted.
  </p>

example: |
  duk_push_object(ctx);                           /* [ ... obj ] */
  duk_push_int(ctx, 42);                          /* [ ... obj 42 ] */
  duk_put_prop_string(ctx, -2, "meaningOfLife");  /* [ ... obj ] */
  duk_compact(ctx, -1);                           /* [ ... obj ] */

tags:
  - object
  - property
  - memory

introduced: 1.0.0