<?xml version="1.0"?>
<page id="memory"
      type="guide"
      style="class"
      xmlns="http://projectmallard.org/1.0/"
      xmlns:api="http://projectmallard.org/experimental/api/"
      xmlns:ui="http://projectmallard.org/experimental/ui/">

  <info>
    <link type="guide" xref="index#api-reference" />
  </info>

  <title>Memory Management</title>
  <subtitle>BSON Memory Abstraction</subtitle>

  <section id="description">
    <title>Description</title>
    <p>Libbson contains a lightweight memory abstraction to make portability to new platforms easier. Additionally, it helps us integrate with interesting higher-level languages. One caveat, however, is that Libbson is not designed to deal with Out of Memory (OOM) situations. Doing so requires extreme dilligence throughout the application stack that has rarely been implemented correctly. This may change in the future. As it stands now, Libbson will <code>abort()</code> under OOM situations.</p>
    <p>To aid in language binding integration, Libbson allows for setting a custom memory allocator via <code xref="bson_mem_set_vtable">bson_mem_set_vtable()</code>.  This allocation may be reversed via <code xref="bson_mem_restore_vtable">bson_mem_restore_vtable()</code>.</p>
  </section>

  <links type="topic" groups="function" style="2column">
    <title>Functions</title>
  </links>
</page>
