mozilla

Revision 6755 of Mozilla Framework Based on Templates (MFBT)

  • Revision slug: Mozilla/MFBT
  • Revision title: Mozilla Framework Based on Templates (MFBT)
  • Revision id: 6755
  • Created:
  • Creator: Waldo
  • Is current revision? No
  • Comment reorder slightly; 52 words added, 67 words removed
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/StandardInteger.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

Types and type manipulation

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

{{ Source("mfbt/Types.h", "Types.h") }} further provides size_t.

{{ Source("mfbt/CheckedInt.h", "CheckedInt.h") }} implements checked integers. They behave like integer, but safely check for integer overflow and divide-by-zero. Useful for input validation.

{{ Source("mfbt/FloatingPoint.h", "FloatingPoint.h") }} provides various operations for examining and working upon double-precision floating point values, and for producing various special floating point values.

Core

{{ Source("mfbt/Types.h", "Types.h") }} further provides 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/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") }}.

{{ 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/Scoped.h", "Scoped.h") }} implements scope-based resource management, to simplify the task of cleaning-up resources when leaving a scope.

{{ Source("mfbt/ThreadLocal.h", "ThreadLocal.h") }} implements thread-local storage, aka "TLS", also called thread-specific storage. It should be used only for static-storage-duration variables, such as global variables or static class members.

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/StandardInteger.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>Types and type manipulation</h3>
<p>The <code>&lt;stdint.h&gt;</code> standard header is not available on all platforms, so mfbt provides the <code>{{ Source("mfbt/StandardInteger.h", "StandardInteger.h") }}</code> header which implements its functionality.</p>
<p><code>{{ Source("mfbt/Types.h", "Types.h") }}</code> further provides <code>size_t</code>.</p>
<p><code>{{ Source("mfbt/CheckedInt.h", "CheckedInt.h") }}</code> implements checked integers. They behave like integer, but safely check for integer overflow and divide-by-zero. Useful for input validation.</p>
<p>{{ Source("mfbt/FloatingPoint.h", "FloatingPoint.h") }} provides various operations for examining and working upon double-precision floating point values, and for producing various special floating point values.</p><h3>Core</h3>
<p><code>{{ Source("mfbt/Types.h", "Types.h") }}</code> further provides 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/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>
<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/Scoped.h", "Scoped.h") }}</code> implements scope-based resource management, to simplify the task of cleaning-up resources when leaving a scope.</p>
<p><code>{{ Source("mfbt/ThreadLocal.h", "ThreadLocal.h") }}</code> implements thread-local storage, aka "TLS", also called thread-specific storage. It should be used only for static-storage-duration variables, such as global variables or static class members.</p>
Revert to this revision