Revision 6743 of Mozilla Framework Based on Templates (MFBT)

  • Revision slug: Mozilla/MFBT
  • Revision title: Mozilla Framework Based on Templates (MFBT)
  • Revision id: 6743
  • Created:
  • Creator: jlebar
  • Is current revision? No
  • Comment Adding LinkedList; 51 words added
Tags: 

Revision Content

The Mozilla Framework Based on Templates ("mfbt") is the central repository for macros, functions, and data structures used throughout Mozilla code, including in the JavaScript engine.  Its code resides in the {{ Source("mfbt/") }} source directory, but headers within it should be included using paths like "mozilla/StdInt.h".  It is fairly new, so its functionality is currently sparse.  Feel free to file bugs to add new functionality to it, or to move existing functionality into, it as needed.

mfbt code goes to some length to document all its interfaces in comments, including examples when possible.  It also attempts to define its functionality in well-named files, such that simply skimming the contents of {{ Source("mfbt/") }} will quickly suggest the relevant header to examine.  Therefore this document primarily attempts to direct readers to the correct file to read those comments.  Feel free to file a documentation bug if you think this approach could be improved, and feel free to make improvements to this document if you see them.

Functionality

Core

The <stdint.h> standard header is not available on all platforms, so mfbt provides the {{ Source("mfbt/StdInt.h", "StdInt.h") }} header which implements its functionality.

If you need more than simply <stdint.h>'s types, {{ Source("mfbt/Types.h", "Types.h") }} further provides size_t.

{{ Source("mfbt/Types.h", "Types.h") }} also provides well as macros to define imported and exported C symbols.

{{ Source("mfbt/Attributes.h", "Attributes.h") }} implements various function and class attribute macros.  The function macros control inlining, note whether a function returns, and enforce various C++-related restrictions on inheritance and use.  The class macros permit controlling the inheritability of a class.

{{ Source("mfbt/Util.h", "Util.h") }} implements various other bits of useful functionality.  (This header will likely be further split up so that its functionality is less grab-bag.)

Debugging

Assertions can be invaluable at smoking out bugs during development.  mfbt provides assertion macros in {{ Source("mfbt/Assertions.h", "Assertions.h") }} implementing runtime assertions and compile-time assertions.

RAII is a powerful pattern.  Yet when the the relevant class is used only for the side effects of its constructor and destructor, it's easy to create the guard instance with shorter lifetime than was intended, if you forget to name the guard instance.  {{ Source("mfbt/GuardObjects.h", "GuardObjects.h") }} provides macros which can be used to annotate a guard class, so that any attempt to create an unnamed temporary for it will assert.

Data structures

{{ Source("mfbt/RangedPtr.h", "RangedPtr.h") }} implements RangedPtr, a smart pointer template whose value may be manipulated only within a range specified at construction time, and which may be dereferenced only at valid locations in that range.  This pointer is a useful way to expose access to values within an array.

{{ Source("mfbt/RefPtr.h", "RefPtr.h") }} implements various smart pointer templates to simplify reference counting of values of particular classes.

{{ Source("mfbt/LinkedList.h", "LinkedList.h") }} implements a type-safe doubly-linked list class. Most new code should use this rather than {{ Source("nsprpub/pr/include/prclist.h", PRCList) }}.

Revision Source

<p>The Mozilla Framework Based on Templates ("mfbt") is the central repository for macros, functions, and data structures used throughout Mozilla code, including in the JavaScript engine.  Its code resides in the <code>{{ Source("mfbt/") }}</code> source directory, but headers within it should be included using paths like <code>"mozilla/StdInt.h"</code>.  It is fairly new, so its functionality is currently sparse.  Feel free to <a class="link-https" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Core&amp;product=MFBT" title="https://bugzilla.mozilla.org/enter_bug.cgi?product=Core&amp;product=MFBT">file bugs</a> to add new functionality to it, or to move existing functionality into, it as needed.</p>
<p>mfbt code goes to some length to document all its interfaces in comments, including examples when possible.  It also attempts to define its functionality in well-named files, such that simply skimming the contents of <code>{{ Source("mfbt/") }}</code> will quickly suggest the relevant header to examine.  Therefore this document primarily attempts to direct readers to the correct file to read those comments.  Feel free to file a <a class="link-https" href="https://bugzilla.mozilla.org/enter_bug.cgi?bug_status=NEW&amp;cc=mfbt%40core.bugs&amp;comment=&amp;component=Documentation%20Requests&amp;product=Mozilla%20Developer%20Network&amp;qa_contact=doc-request%40mdn.bugs&amp;rep_platform=All&amp;op_sys=All" title="https://bugzilla.mozilla.org/enter_bug.cgi?bug_status=NEW&amp;cc=mfbt%40core.bugs&amp;comment=&amp;component=Documentation%20Requests&amp;product=Mozilla%20Developer%20Network&amp;qa_contact=doc-request%40mdn.bugs&amp;rep_platform=All&amp;op_sys=All">documentation bug</a> if you think this approach could be improved, and feel free to make improvements to this document if you see them.</p>
<h2>Functionality</h2>
<h3>Core</h3>
<p>The <code>&lt;stdint.h&gt;</code> standard header is not available on all platforms, so mfbt provides the <code>{{ Source("mfbt/StdInt.h", "StdInt.h") }}</code> header which implements its functionality.</p>
<p>If you need more than simply <code>&lt;stdint.h&gt;</code>'s types, <code>{{ Source("mfbt/Types.h", "Types.h") }}</code> further provides <code>size_t</code>.</p>
<p><code>{{ Source("mfbt/Types.h", "Types.h") }}</code> also provides well as macros to define imported and exported C symbols.</p>
<p><code>{{ Source("mfbt/Attributes.h", "Attributes.h") }}</code> implements various function and class attribute macros.  The function macros control inlining, note whether a function returns, and enforce various C++-related restrictions on inheritance and use.  The class macros permit controlling the inheritability of a class.</p>
<p><code>{{ Source("mfbt/Util.h", "Util.h") }}</code> implements various other bits of useful functionality.  (This header will likely be further split up so that its functionality is less grab-bag.)</p>
<h3>Debugging</h3>
<p>Assertions can be invaluable at smoking out bugs during development.  mfbt provides assertion macros in <code>{{ Source("mfbt/Assertions.h", "Assertions.h") }} </code>implementing runtime assertions and compile-time assertions.</p>
<p><a class=" external" href="http://en.wikipedia.org/wiki/RAII" title="http://en.wikipedia.org/wiki/RAII">RAII</a> is a powerful pattern.  Yet when the the relevant class is used only for the side effects of its constructor and destructor, it's easy to create the guard instance with shorter lifetime than was intended, if you forget to name the guard instance.  <code>{{ Source("mfbt/GuardObjects.h", "GuardObjects.h") }}</code> provides macros which can be used to annotate a guard class, so that any attempt to create an unnamed temporary for it will assert.</p>
<h3>Data structures</h3>
<p><code>{{ Source("mfbt/RangedPtr.h", "RangedPtr.h") }} </code>implements <code>RangedPtr</code>, a smart pointer template whose value may be manipulated only within a range specified at construction time, and which may be dereferenced only at valid locations in that range.  This pointer is a useful way to expose access to values within an array.</p>
<p><code>{{ Source("mfbt/RefPtr.h", "RefPtr.h") }} </code>implements various smart pointer templates to simplify reference counting of values of particular classes.</p>
<p><code>{{ Source("mfbt/LinkedList.h", "LinkedList.h") }}</code> implements a type-safe doubly-linked list class. Most new code should use this rather than <code>{{ Source("nsprpub/pr/include/prclist.h", PRCList) }}</code>.</p>
Revert to this revision