158 lines
17 KiB
HTML
158 lines
17 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.8.11"/>
|
|
<title>MPack: Introduction</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<script type="text/javascript">
|
|
$(document).ready(function() { init_search(); });
|
|
</script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
<link href="doxygen-mpack-css.css" rel="stylesheet" type="text/css"/>
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
|
<div id="projectname">MPack
|
|
 <span id="projectnumber">0.8.2</span>
|
|
</div>
|
|
<div id="projectbrief">A C encoding/decoding library for the MessagePack serialization format.</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.8.11 -->
|
|
<script type="text/javascript">
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
</script>
|
|
<div id="navrow1" class="tabs">
|
|
<ul class="tablist">
|
|
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
|
|
<li><a href="pages.html"><span>Pages</span></a></li>
|
|
<li><a href="modules.html"><span>Modules</span></a></li>
|
|
<li>
|
|
<div id="MSearchBox" class="MSearchBoxInactive">
|
|
<span class="left">
|
|
<img id="MSearchSelect" src="search/mag_sel.png"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
alt=""/>
|
|
<input type="text" id="MSearchField" value="Search" accesskey="S"
|
|
onfocus="searchBox.OnSearchFieldFocus(true)"
|
|
onblur="searchBox.OnSearchFieldFocus(false)"
|
|
onkeyup="searchBox.OnSearchFieldChange(event)"/>
|
|
</span><span class="right">
|
|
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
|
|
</span>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div><!-- top -->
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
<div class="header">
|
|
<div class="headertitle">
|
|
<div class="title">Introduction </div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p>MPack is a C implementation of an encoder and decoder for the <a href="http://msgpack.org/">MessagePack</a> serialization format. It is intended to be:</p>
|
|
<ul>
|
|
<li>Simple and easy to use</li>
|
|
<li>Secure against untrusted data</li>
|
|
<li>Lightweight, suitable for embedded</li>
|
|
<li><a href="http://ludocode.github.io/mpack/">Extensively documented</a></li>
|
|
<li><a href="https://github.com/ludocode/schemaless-benchmarks#speed---desktop-pc">Extremely fast</a></li>
|
|
</ul>
|
|
<p>The core of MPack contains a buffered reader and writer, and a tree-style parser that decodes into a tree of dynamically typed nodes. Helper functions can be enabled to read values of expected type, to work with files, to allocate strings automatically, to check UTF-8 encoding, and more. The MPack featureset can be configured at compile-time to set which features, components and debug checks are compiled, and what dependencies are available.</p>
|
|
<p>The MPack code is small enough to be embedded directly into your codebase. The easiest way to use it is to download the <a href="https://github.com/ludocode/mpack/releases">amalgamation package</a> and insert the source files directly into your project. Copy <code>mpack.h</code> and <code>mpack.c</code> into to your codebase, and copy <code>mpack-config.h.sample</code> as <code>mpack-config.h</code>. You can use the defaults or edit it if you'd like to customize the MPack featureset.</p>
|
|
<h2>The Node Reader API</h2>
|
|
<p>The Node API parses a chunk of MessagePack data into an immutable tree of dynamically-typed nodes. A series of helper functions can be used to extract data of specific types from each node.</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// parse a file into a node tree</span></div><div class="line"><a class="code" href="group__node.html#ga9c76cfdb08042d6412b5c745bca928a7">mpack_tree_t</a> tree;</div><div class="line"><a class="code" href="group__node.html#ga2f8327cf4ebc79d9358ee0a1643af66c">mpack_tree_init_file</a>(&tree, <span class="stringliteral">"homepage-example.mp"</span>, 0);</div><div class="line"><a class="code" href="group__node.html#ga08f46371c0c59a2e4dd7bdf1891fb3cb">mpack_node_t</a> root = <a class="code" href="group__node.html#ga2c49262ce28699d5ec90db09b5fd2eee">mpack_tree_root</a>(&tree);</div><div class="line"></div><div class="line"><span class="comment">// extract the example data on the msgpack homepage</span></div><div class="line"><span class="keywordtype">bool</span> compact = <a class="code" href="group__node.html#gad15f3dba3fe1c0b5b7d9ed5d2c34215a">mpack_node_bool</a>(<a class="code" href="group__node.html#ga6ce515ec366036b1602bafe65a56ef7e">mpack_node_map_cstr</a>(root, <span class="stringliteral">"compact"</span>));</div><div class="line"><span class="keywordtype">int</span> schema = <a class="code" href="group__node.html#ga0180b62e35f1438807cec5f1dc747f3d">mpack_node_i32</a>(<a class="code" href="group__node.html#ga6ce515ec366036b1602bafe65a56ef7e">mpack_node_map_cstr</a>(root, <span class="stringliteral">"schema"</span>));</div><div class="line"></div><div class="line"><span class="comment">// clean up and check for errors</span></div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="group__node.html#gabf57acbc8356be8fab13a64f78986fdc">mpack_tree_destroy</a>(tree) != <a class="code" href="group__common.html#gga9d9f282ca4183ab5190e09d04c1f74c4a642a07519ef145fc9dd1068230c4a661">mpack_ok</a>) {</div><div class="line"> fprintf(stderr, <span class="stringliteral">"An error occurred decoding the data!\n"</span>);</div><div class="line"> <span class="keywordflow">return</span>;</div><div class="line">}</div></div><!-- fragment --><p>Note that no additional error handling is needed in the above code. If the file is missing or corrupt, if map keys are missing or if nodes are not in the expected types, special "nil" nodes and false/zero values are returned and the tree is placed in an error state. An error check is only needed before using the data.</p>
|
|
<p>The above example decodes into allocated pages of nodes. A fixed node pool can be provided to the parser instead in memory-constrained environments. For maximum performance and minimal memory usage, the <a class="el" href="md_docs_expect.html">Expect API</a> can be used to parse data of a predefined schema.</p>
|
|
<h2>The Write API</h2>
|
|
<p>The MPack Write API encodes structured data to MessagePack.</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// encode to memory buffer</span></div><div class="line"><span class="keywordtype">char</span>* data;</div><div class="line"><span class="keywordtype">size_t</span> size;</div><div class="line"><a class="code" href="group__writer.html#gabdb207d4ba6a6ae47efa5ede13436f31">mpack_writer_t</a> writer;</div><div class="line"><a class="code" href="group__writer.html#ga0aa3b265fb5ece9c4cba0f2b1bfbdb53">mpack_writer_init_growable</a>(&writer, &data, &size);</div><div class="line"></div><div class="line"><span class="comment">// write the example on the msgpack homepage</span></div><div class="line"><a class="code" href="group__writer.html#ga5c54c857ce7f0bdcea9b2df349cbcc61">mpack_start_map</a>(&writer, 2);</div><div class="line"><a class="code" href="group__writer.html#ga3bd01df04f36b5feb770f449b83995b6">mpack_write_cstr</a>(&writer, <span class="stringliteral">"compact"</span>);</div><div class="line"><a class="code" href="group__writer.html#ga5d8fa89f571534f5ddbdf81f5bbd5de8">mpack_write_bool</a>(&writer, <span class="keyword">true</span>);</div><div class="line"><a class="code" href="group__writer.html#ga3bd01df04f36b5feb770f449b83995b6">mpack_write_cstr</a>(&writer, <span class="stringliteral">"schema"</span>);</div><div class="line"><a class="code" href="group__writer.html#gab2e3cd22bad53b31bed85d7b46d135c9">mpack_write_uint</a>(&writer, 0);</div><div class="line"><a class="code" href="group__writer.html#gabf0ab209845e7c9c3df7aa00b0d59a03">mpack_finish_map</a>(&writer);</div><div class="line"></div><div class="line"><span class="comment">// finish writing</span></div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="group__writer.html#ga1cf5a2d9b687d94f637a36123ef7cec0">mpack_writer_destroy</a>(&writer) != <a class="code" href="group__common.html#gga9d9f282ca4183ab5190e09d04c1f74c4a642a07519ef145fc9dd1068230c4a661">mpack_ok</a>) {</div><div class="line"> fprintf(stderr, <span class="stringliteral">"An error occurred encoding the data!\n"</span>);</div><div class="line"> <span class="keywordflow">return</span>;</div><div class="line">}</div><div class="line"></div><div class="line"><span class="comment">// use the data</span></div><div class="line">do_something_with_data(data, size);</div><div class="line">free(data);</div></div><!-- fragment --><p>In the above example, we encode to a growable memory buffer. The writer can instead write to a pre-allocated or stack-allocated buffer, avoiding the need for memory allocation. The writer can also be provided with a flush function (such as a file or socket write function) to call when the buffer is full or when writing is done.</p>
|
|
<p>If any error occurs, the writer is placed in an error state. The writer will flag an error if too much data is written, if the wrong number of elements are written, if the data could not be flushed, etc. No additional error handling is needed in the above code; any subsequent writes are ignored when the writer is in an error state, so you don't need to check every write for errors.</p>
|
|
<p>Note in particular that in debug mode, the <code><a class="el" href="group__writer.html#gabf0ab209845e7c9c3df7aa00b0d59a03" title="Finishes writing a map. ">mpack_finish_map()</a></code> call above ensures that two key/value pairs were actually written as claimed, something that other MessagePack C/C++ libraries may not do.</p>
|
|
<h2>Comparison With Other Parsers</h2>
|
|
<p>MPack is rich in features while maintaining very high performance and a small code footprint. Here's a short feature table comparing it to other C parsers:</p>
|
|
<table class="doxtable">
|
|
<tr>
|
|
<th align="left"></th><th align="center"><a href="https://github.com/ludocode/mpack">MPack</a><br />
|
|
(v0.8) </th><th align="center"><a href="https://github.com/msgpack/msgpack-c">msgpack-c</a><br />
|
|
(v1.3.0) </th><th align="center"><a href="https://github.com/camgunz/cmp">CMP</a><br />
|
|
(v14) </th></tr>
|
|
<tr>
|
|
<td align="left">No libc requirement </td><td align="center">✓ </td><td align="center"></td><td align="center">✓ </td></tr>
|
|
<tr>
|
|
<td align="left">Growable memory writer </td><td align="center">✓ </td><td align="center">✓ </td><td align="center"></td></tr>
|
|
<tr>
|
|
<td align="left">File I/O helpers </td><td align="center">✓ </td><td align="center">✓ </td><td align="center"></td></tr>
|
|
<tr>
|
|
<td align="left">Tree parser </td><td align="center">✓ </td><td align="center">✓ </td><td align="center"></td></tr>
|
|
<tr>
|
|
<td align="left">Propagating errors </td><td align="center">✓ </td><td align="center"></td><td align="center">✓ </td></tr>
|
|
<tr>
|
|
<td align="left">Compound size tracking </td><td align="center">✓ </td><td align="center"></td><td align="center"></td></tr>
|
|
<tr>
|
|
<td align="left">Incremental parser </td><td align="center">✓ </td><td align="center"></td><td align="center">✓ </td></tr>
|
|
<tr>
|
|
<td align="left">Incremental range/match helpers </td><td align="center">✓ </td><td align="center"></td><td align="center"></td></tr>
|
|
<tr>
|
|
<td align="left">Tree stream parser </td><td align="center"></td><td align="center">✓ </td><td align="center"></td></tr>
|
|
<tr>
|
|
<td align="left">UTF-8 verification </td><td align="center">✓ </td><td align="center"></td><td align="center"></td></tr>
|
|
</table>
|
|
<p>A larger feature comparison table is available <a class="el" href="md_docs_features.html">here</a> which includes descriptions of the various entries in the table.</p>
|
|
<p><a href="https://github.com/ludocode/schemaless-benchmarks">This benchmarking suite</a> compares the performance of MPack to other implementations of schemaless serialization formats. MPack outperforms all JSON and MessagePack libraries, and in some tests MPack is several times faster than <a href="https://github.com/miloyip/rapidjson">RapidJSON</a> for equivalent data.</p>
|
|
<h2>Why Not Just Use JSON?</h2>
|
|
<p>Conceptually, MessagePack stores data similarly to JSON: they are both composed of simple values such as numbers and strings, stored hierarchically in maps and arrays. So why not just use JSON instead? The main reason is that JSON is designed to be human-readable, so it is not as efficient as a binary serialization format:</p>
|
|
<ul>
|
|
<li>Compound types such as strings, maps and arrays are delimited, so appropriate storage cannot be allocated upfront. The whole object must be parsed to determine its size.</li>
|
|
<li>Strings are not stored in their native encoding. Special characters such as quotes and backslashes must be escaped when written and converted back when read.</li>
|
|
<li>Numbers are particularly inefficient (especially when parsing back floats), making JSON inappropriate as a base format for structured data that contains lots of numbers.</li>
|
|
<li>Binary data is not supported by JSON at all. Small binary blobs such as icons and thumbnails need to be Base64 encoded or passed out-of-band.</li>
|
|
</ul>
|
|
<p>The above issues greatly increase the complexity of the decoder. Full-featured JSON decoders are quite large, and minimal decoders tend to leave out such features as string unescaping and float parsing, instead leaving these up to the user or platform. This can lead to hard-to-find platform-specific and locale-specific bugs, as well as a greater potential for security vulnerabilites. This also significantly decreases performance, making JSON unattractive for use in applications such as mobile games.</p>
|
|
<p>While the space inefficiencies of JSON can be partially mitigated through minification and compression, the performance inefficiencies cannot. More importantly, if you are minifying and compressing the data, then why use a human-readable format in the first place?</p>
|
|
<h2>Running the Unit Tests</h2>
|
|
<p>The MPack build process does not build MPack into a library; it is used to build and run the unit tests. You do not need to build MPack or the unit testing suite to use MPack.</p>
|
|
<p>On Linux, the test suite uses SCons and requires Valgrind, and can be run in the repository or in the amalgamation package. Run <code>scons</code> to build and run the test suite in full debug configuration.</p>
|
|
<p>On Windows, there is a Visual Studio solution, and on OS X, there is an Xcode project for building and running the test suite.</p>
|
|
<p>You can also build and run the test suite in all supported configurations, which is what the continuous integration server will build and run. If you are on 64-bit, you will need support for cross-compiling to 32-bit, and running 32-bit binaries with 64-bit Valgrind. On Ubuntu, you'll need <code>libc6-dbg:i386</code>. On Arch you'll need <code>gcc-multilib</code> or <code>lib32-clang</code>, and <code>valgrind-multilib</code>. Use <code>scons all=1 -j16</code> (or some appropriate thread count) to build and run all tests. </p>
|
|
</div></div><!-- contents -->
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated by  <a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/>
|
|
</a> 1.8.11
|
|
</small></address>
|
|
</body>
|
|
</html>
|