skimr

<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta name="generator" content="pandoc" /> <meta http-equiv="X-UA-Compatible" content="IE=EDGE" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>FAQ</title> <script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to // be compatible with the behavior of Pandoc < 2.8). document.addEventListener('DOMContentLoaded', function(e) { var hs = document.querySelectorAll("div.section[class*='level'] > :first-child"); var i, h, a; for (i = 0; i < hs.length; i++) { h = hs[i]; if (!/^h[1-6]$/i.test(h.tagName)) continue; // it should be a header h1-h6 a = h.attributes; while (a.length > 0) h.removeAttribute(a[0].name); } }); </script> <style type="text/css"> code{white-space: pre-wrap;} span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} </style> <style type="text/css"> code { white-space: pre; } .sourceCode { overflow: visible; } </style> <style type="text/css" data-origin="pandoc"> pre > code.sourceCode { white-space: pre; position: relative; } pre > code.sourceCode > span { display: inline-block; line-height: 1.25; } pre > code.sourceCode > span:empty { height: 1.2em; } .sourceCode { overflow: visible; } code.sourceCode > span { color: inherit; text-decoration: inherit; } div.sourceCode { margin: 1em 0; } pre.sourceCode { margin: 0; } @media screen { div.sourceCode { overflow: auto; } } @media print { pre > code.sourceCode { white-space: pre-wrap; } pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; } } pre.numberSource code { counter-reset: source-line 0; } pre.numberSource code > span { position: relative; left: -4em; counter-increment: source-line; } pre.numberSource code > span > a:first-child::before { content: counter(source-line); position: relative; left: -1em; text-align: right; vertical-align: baseline; border: none; display: inline-block; -webkit-touch-callout: none; -webkit-user-select: none; -khtml-user-select: none; -moz-user-select: none; -ms-user-select: none; user-select: none; padding: 0 4px; width: 4em; color: #aaaaaa; } pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } div.sourceCode { } @media screen { pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } } code span.al { color: #ff0000; font-weight: bold; } code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } code span.at { color: #7d9029; } code span.bn { color: #40a070; } code span.bu { color: #008000; } code span.cf { color: #007020; font-weight: bold; } code span.ch { color: #4070a0; } code span.cn { color: #880000; } code span.co { color: #60a0b0; font-style: italic; } code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } code span.do { color: #ba2121; font-style: italic; } code span.dt { color: #902000; } code span.dv { color: #40a070; } code span.er { color: #ff0000; font-weight: bold; } code span.ex { } code span.fl { color: #40a070; } code span.fu { color: #06287e; } code span.im { color: #008000; font-weight: bold; } code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } code span.kw { color: #007020; font-weight: bold; } code span.op { color: #666666; } code span.ot { color: #007020; } code span.pp { color: #bc7a00; } code span.sc { color: #4070a0; } code span.ss { color: #bb6688; } code span.st { color: #4070a0; } code span.va { color: #19177c; } code span.vs { color: #4070a0; } code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } </style> <script> // apply pandoc div.sourceCode style to pre.sourceCode instead (function() { var sheets = document.styleSheets; for (var i = 0; i < sheets.length; i++) { if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue; try { var rules = sheets[i].cssRules; } catch (e) { continue; } var j = 0; while (j < rules.length) { var rule = rules[j]; // check if there is a div.sourceCode rule if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") { j++; continue; } var style = rule.style.cssText; // check if color or background-color is set if (rule.style.color === '' && rule.style.backgroundColor === '') { j++; continue; } // replace div.sourceCode by a pre.sourceCode rule sheets[i].deleteRule(j); sheets[i].insertRule('pre.sourceCode{' + style + '}', j); } } })(); </script> <style type="text/css">body { background-color: #fff; margin: 1em auto; max-width: 700px; overflow: visible; padding-left: 2em; padding-right: 2em; font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; font-size: 14px; line-height: 1.35; } #TOC { clear: both; margin: 0 0 10px 10px; padding: 4px; width: 400px; border: 1px solid #CCCCCC; border-radius: 5px; background-color: #f6f6f6; font-size: 13px; line-height: 1.3; } #TOC .toctitle { font-weight: bold; font-size: 15px; margin-left: 5px; } #TOC ul { padding-left: 40px; margin-left: -1.5em; margin-top: 5px; margin-bottom: 5px; } #TOC ul ul { margin-left: -2em; } #TOC li { line-height: 16px; } table { margin: 1em auto; border-width: 1px; border-color: #DDDDDD; border-style: outset; border-collapse: collapse; } table th { border-width: 2px; padding: 5px; border-style: inset; } table td { border-width: 1px; border-style: inset; line-height: 18px; padding: 5px 5px; } table, table th, table td { border-left-style: none; border-right-style: none; } table thead, table tr.even { background-color: #f7f7f7; } p { margin: 0.5em 0; } blockquote { background-color: #f6f6f6; padding: 0.25em 0.75em; } hr { border-style: solid; border: none; border-top: 1px solid #777; margin: 28px 0; } dl { margin-left: 0; } dl dd { margin-bottom: 13px; margin-left: 13px; } dl dt { font-weight: bold; } ul { margin-top: 0; } ul li { list-style: circle outside; } ul ul { margin-bottom: 0; } pre, code { background-color: #f7f7f7; border-radius: 3px; color: #333; white-space: pre-wrap; } pre { border-radius: 3px; margin: 5px 0px 10px 0px; padding: 10px; } pre:not([class]) { background-color: #f7f7f7; } code { font-family: Consolas, Monaco, 'Courier New', monospace; font-size: 85%; } p > code, li > code { padding: 2px 0px; } div.figure { text-align: center; } img { background-color: #FFFFFF; padding: 2px; border: 1px solid #DDDDDD; border-radius: 3px; border: 1px solid #CCCCCC; margin: 0 5px; } h1 { margin-top: 0; font-size: 35px; line-height: 40px; } h2 { border-bottom: 4px solid #f7f7f7; padding-top: 10px; padding-bottom: 2px; font-size: 145%; } h3 { border-bottom: 2px solid #f7f7f7; padding-top: 10px; font-size: 120%; } h4 { border-bottom: 1px solid #f7f7f7; margin-left: 8px; font-size: 105%; } h5, h6 { border-bottom: 1px solid #ccc; font-size: 105%; } a { color: #0033dd; text-decoration: none; } a:hover { color: #6666ff; } a:visited { color: #800080; } a:visited:hover { color: #BB00BB; } a[href^="http:"] { text-decoration: underline; } a[href^="https:"] { text-decoration: underline; } code > span.kw { color: #555; font-weight: bold; } code > span.dt { color: #902000; } code > span.dv { color: #40a070; } code > span.bn { color: #d14; } code > span.fl { color: #d14; } code > span.ch { color: #d14; } code > span.st { color: #d14; } code > span.co { color: #888888; font-style: italic; } code > span.ot { color: #007020; } code > span.al { color: #ff0000; font-weight: bold; } code > span.fu { color: #900; font-weight: bold; } code > span.er { color: #a61717; background-color: #e3d2d2; } </style> </head> <body> <h1 class="title toc-ignore">FAQ</h1> Below are some Frequently Asked Questions about cpp11. If you have a question that you think would fit well here please <a href="https://github.com/r-lib/cpp11/issues/new/choose">open an issue</a>. <div id="what-are-the-underlying-types-of-cpp11-objects" class="section level4"> <h4>1. What are the underlying types of cpp11 objects?</h4> <table> <thead> <tr class="header"> <th>vector</th> <th>element</th> </tr> </thead> <tbody> <tr class="odd"> <td>cpp11::integers</td> <td>int</td> </tr> <tr class="even"> <td>cpp11::doubles</td> <td>double</td> </tr> <tr class="odd"> <td>cpp11::logicals</td> <td>cpp11::r_bool</td> </tr> <tr class="even"> <td>cpp11::strings</td> <td>cpp11::r_string</td> </tr> <tr class="odd"> <td>cpp11::raws</td> <td>uint8_t</td> </tr> <tr class="even"> <td>cpp11::list</td> <td>SEXP</td> </tr> </tbody> </table> </div> <div id="how-do-i-add-elements-to-a-named-list" class="section level4"> <h4>2. How do I add elements to a named list?</h4> Use the <code>push_back()</code> method with the named literal syntax. The named literal syntax is defined in the <code>cpp11::literals</code> namespace. <div class="sourceCode" id="cb1"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb1-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb1-2" tabindex="-1"></a> <a href="#cb1-3" tabindex="-1"></a>[[cpp11::register]] <a href="#cb1-4" tabindex="-1"></a>cpp11::list foo_push() { <a href="#cb1-5" tabindex="-1"></a> using namespace cpp11::literals; <a href="#cb1-6" tabindex="-1"></a> <a href="#cb1-7" tabindex="-1"></a> cpp11::writable::list x; <a href="#cb1-8" tabindex="-1"></a> x.push_back({"foo"_nm = 1}); <a href="#cb1-9" tabindex="-1"></a> <a href="#cb1-10" tabindex="-1"></a> return x; <a href="#cb1-11" tabindex="-1"></a>}</code></pre></div> </div> <div id="does-cpp11-support-default-arguments" class="section level4"> <h4>3. Does cpp11 support default arguments?</h4> cpp11 does not support default arguments, while convenient they would require more complexity to support than is currently worthwhile. If you need default argument support you can use a wrapper function around your cpp11 registered function. A common convention is to name the internal function with a trailing <code>_</code>. <div class="sourceCode" id="cb2"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb2-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb2-2" tabindex="-1"></a>[[cpp11::register]] <a href="#cb2-3" tabindex="-1"></a>double add_some_(double x, double amount) { <a href="#cb2-4" tabindex="-1"></a> return x + amount; <a href="#cb2-5" tabindex="-1"></a>}</code></pre></div> <div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb3-1" tabindex="-1"></a>add_some <- function(x, amount = 1) { <a href="#cb3-2" tabindex="-1"></a> add_some_(x, amount) <a href="#cb3-3" tabindex="-1"></a>} <a href="#cb3-4" tabindex="-1"></a>add_some(1) <a href="#cb3-5" tabindex="-1"></a>#> [1] 2 <a href="#cb3-6" tabindex="-1"></a>add_some(1, amount = 5) <a href="#cb3-7" tabindex="-1"></a>#> [1] 6</code></pre></div> </div> <div id="how-do-i-create-a-new-empty-list" class="section level4"> <h4>4. How do I create a new empty list?</h4> Define a new writable list object. <code>cpp11::writable::list x;</code> </div> <div id="how-do-i-retrieve-named-elements-from-a-named-vectorlist" class="section level4"> <h4>5. How do I retrieve (named) elements from a named vector/list?</h4> Use the <code>[]</code> accessor function. <code>x["foo"]</code> </div> <div id="how-can-i-tell-whether-a-vector-is-named" class="section level4"> <h4>6. How can I tell whether a vector is named?</h4> Use the <code>named()</code> method for vector classes. <div class="sourceCode" id="cb4"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb4-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb4-2" tabindex="-1"></a> <a href="#cb4-3" tabindex="-1"></a>[[cpp11::register]] <a href="#cb4-4" tabindex="-1"></a>bool is_named(cpp11::strings x) { <a href="#cb4-5" tabindex="-1"></a> return x.named(); <a href="#cb4-6" tabindex="-1"></a>}</code></pre></div> <div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb5-1" tabindex="-1"></a>is_named("foo") <a href="#cb5-2" tabindex="-1"></a>#> [1] FALSE <a href="#cb5-3" tabindex="-1"></a> <a href="#cb5-4" tabindex="-1"></a>is_named(c(x = "foo")) <a href="#cb5-5" tabindex="-1"></a>#> [1] TRUE</code></pre></div> </div> <div id="how-do-i-return-a-cpp11writablelogicals-object-with-only-a-false-value" class="section level4"> <h4>7. How do I return a <code>cpp11::writable::logicals</code> object with only a <code>FALSE</code> value?</h4> You need to use <a href="https://en.cppreference.com/w/cpp/language/list_initialization">list initialization</a> with <code>{}</code> to create the object. <div class="sourceCode" id="cb6"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb6-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb6-2" tabindex="-1"></a> <a href="#cb6-3" tabindex="-1"></a>[[cpp11::register]] <a href="#cb6-4" tabindex="-1"></a>cpp11::writable::logicals my_false() { <a href="#cb6-5" tabindex="-1"></a> return {FALSE}; <a href="#cb6-6" tabindex="-1"></a>} <a href="#cb6-7" tabindex="-1"></a> <a href="#cb6-8" tabindex="-1"></a>[[cpp11::register]] <a href="#cb6-9" tabindex="-1"></a>cpp11::writable::logicals my_true() { <a href="#cb6-10" tabindex="-1"></a> return {TRUE}; <a href="#cb6-11" tabindex="-1"></a>} <a href="#cb6-12" tabindex="-1"></a> <a href="#cb6-13" tabindex="-1"></a>[[cpp11::register]] <a href="#cb6-14" tabindex="-1"></a>cpp11::writable::logicals my_both() { <a href="#cb6-15" tabindex="-1"></a> return {TRUE, FALSE, TRUE}; <a href="#cb6-16" tabindex="-1"></a>}</code></pre></div> <div class="sourceCode" id="cb7"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb7-1" tabindex="-1"></a>my_false() <a href="#cb7-2" tabindex="-1"></a>#> [1] FALSE <a href="#cb7-3" tabindex="-1"></a> <a href="#cb7-4" tabindex="-1"></a>my_true() <a href="#cb7-5" tabindex="-1"></a>#> [1] TRUE <a href="#cb7-6" tabindex="-1"></a> <a href="#cb7-7" tabindex="-1"></a>my_both() <a href="#cb7-8" tabindex="-1"></a>#> [1] TRUE FALSE TRUE</code></pre></div> </div> <div id="how-do-i-create-a-new-empty-environment" class="section level4"> <h4>8. How do I create a new empty environment?</h4> To do this you need to call the <code>base::new.env()</code> function from C++. This can be done by creating a <code>cpp11::function</code> object and then calling it to generate the new environment. <div class="sourceCode" id="cb8"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb8-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb8-2" tabindex="-1"></a> <a href="#cb8-3" tabindex="-1"></a>[[cpp11::register]] <a href="#cb8-4" tabindex="-1"></a>cpp11::environment create_environment() { <a href="#cb8-5" tabindex="-1"></a> cpp11::function new_env(cpp11::package("base")["new.env"]); <a href="#cb8-6" tabindex="-1"></a> return new_env(); <a href="#cb8-7" tabindex="-1"></a>}</code></pre></div> </div> <div id="how-do-i-assign-and-retrieve-values-in-an-environment-what-happens-if-i-try-to-get-a-value-that-doesnt-exist" class="section level4"> <h4>9. How do I assign and retrieve values in an environment? What happens if I try to get a value that doesn’t exist?</h4> Use <code>[]</code> to retrieve or assign values from an environment by name. If a value does not exist it will return <code>R_UnboundValue</code>. <div class="sourceCode" id="cb9"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb9-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb9-2" tabindex="-1"></a> <a href="#cb9-3" tabindex="-1"></a>[[cpp11::register]] <a href="#cb9-4" tabindex="-1"></a>bool foo_exists(cpp11::environment x) { <a href="#cb9-5" tabindex="-1"></a> return x["foo"] != R_UnboundValue; <a href="#cb9-6" tabindex="-1"></a>} <a href="#cb9-7" tabindex="-1"></a> <a href="#cb9-8" tabindex="-1"></a>[[cpp11::register]] <a href="#cb9-9" tabindex="-1"></a>void set_foo(cpp11::environment x, double value) { <a href="#cb9-10" tabindex="-1"></a> x["foo"] = value; <a href="#cb9-11" tabindex="-1"></a>}</code></pre></div> <div class="sourceCode" id="cb10"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb10-1" tabindex="-1"></a>x <- new.env() <a href="#cb10-2" tabindex="-1"></a> <a href="#cb10-3" tabindex="-1"></a>foo_exists(x) <a href="#cb10-4" tabindex="-1"></a>#> [1] FALSE <a href="#cb10-5" tabindex="-1"></a> <a href="#cb10-6" tabindex="-1"></a>set_foo(x, 1) <a href="#cb10-7" tabindex="-1"></a> <a href="#cb10-8" tabindex="-1"></a>foo_exists(x) <a href="#cb10-9" tabindex="-1"></a>#> [1] TRUE</code></pre></div> </div> <div id="how-can-i-create-a-cpp11raws-from-a-stdstring" class="section level4"> <h4>10. How can I create a <code>cpp11:raws</code> from a <code>std::string</code>?</h4> There is no built in way to do this. One method would be to <code>push_back()</code> each element of the string individually. <div class="sourceCode" id="cb11"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb11-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb11-2" tabindex="-1"></a> <a href="#cb11-3" tabindex="-1"></a>[[cpp11::register]] <a href="#cb11-4" tabindex="-1"></a>cpp11::raws push_raws() { <a href="#cb11-5" tabindex="-1"></a> std::string x("hi"); <a href="#cb11-6" tabindex="-1"></a> cpp11::writable::raws out; <a href="#cb11-7" tabindex="-1"></a> <a href="#cb11-8" tabindex="-1"></a> for (auto c : x) { <a href="#cb11-9" tabindex="-1"></a> out.push_back(c); <a href="#cb11-10" tabindex="-1"></a> } <a href="#cb11-11" tabindex="-1"></a> <a href="#cb11-12" tabindex="-1"></a> return out; <a href="#cb11-13" tabindex="-1"></a>}</code></pre></div> <div class="sourceCode" id="cb12"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb12-1" tabindex="-1"></a>push_raws() <a href="#cb12-2" tabindex="-1"></a>#> [1] 68 69</code></pre></div> </div> <div id="how-can-i-create-a-stdstring-from-a-cpp11writablestring" class="section level4"> <h4>11. How can I create a <code>std::string</code> from a <code>cpp11::writable::string</code>?</h4> Because C++ does not allow for two implicit cast, explicitly cast to <code>cpp11::r_string</code> first. <div class="sourceCode" id="cb13"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb13-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb13-2" tabindex="-1"></a>#include <string> <a href="#cb13-3" tabindex="-1"></a> <a href="#cb13-4" tabindex="-1"></a>[[cpp11::register]] <a href="#cb13-5" tabindex="-1"></a>std::string my_string() { <a href="#cb13-6" tabindex="-1"></a> cpp11::writable::strings x({"foo", "bar"}); <a href="#cb13-7" tabindex="-1"></a> std::string elt = cpp11::r_string(x[0]); <a href="#cb13-8" tabindex="-1"></a> return elt; <a href="#cb13-9" tabindex="-1"></a>}</code></pre></div> </div> <div id="what-are-the-types-for-c-iterators" class="section level4"> <h4>12. What are the types for C++ iterators?</h4> The iterators are <code>::iterator</code> classes contained inside the vector classes. For example the iterator for <code>cpp11::doubles</code> would be <code>cpp11::doubles::iterator</code> and the iterator for <code>cpp11::writable::doubles</code> would be <code>cpp11::writable::doubles::iterator</code>. </div> <div id="my-code-has-using-namespace-std-why-do-i-still-have-to-include-std-in-the-signatures-of-cpp11register-functions" class="section level4"> <h4>13. My code has <code>using namespace std</code>, why do I still have to include <code>std::</code> in the signatures of <code>[[cpp11::register]]</code> functions?</h4> The <code>using namespace std</code> directive will not be included in the generated code of the function signatures, so they still need to be fully qualified. However you will not need to qualify the type names within those functions. The following won’t compile <div class="sourceCode" id="cb14"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb14-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb14-2" tabindex="-1"></a>#include <string> <a href="#cb14-3" tabindex="-1"></a> <a href="#cb14-4" tabindex="-1"></a>using namespace std; <a href="#cb14-5" tabindex="-1"></a> <a href="#cb14-6" tabindex="-1"></a>[[cpp11::register]] <a href="#cb14-7" tabindex="-1"></a>string foobar() { <a href="#cb14-8" tabindex="-1"></a> return string("foo") + "-bar"; <a href="#cb14-9" tabindex="-1"></a>}</code></pre></div> But this will compile and work as intended <div class="sourceCode" id="cb15"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb15-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb15-2" tabindex="-1"></a>#include <string> <a href="#cb15-3" tabindex="-1"></a> <a href="#cb15-4" tabindex="-1"></a>using namespace std; <a href="#cb15-5" tabindex="-1"></a> <a href="#cb15-6" tabindex="-1"></a>[[cpp11::register]] <a href="#cb15-7" tabindex="-1"></a>std::string foobar() { <a href="#cb15-8" tabindex="-1"></a> return string("foo") + "-bar"; <a href="#cb15-9" tabindex="-1"></a>}</code></pre></div> </div> <div id="how-do-i-modify-a-vector-in-place" class="section level4"> <h4>14. How do I modify a vector in place?</h4> In place modification breaks the normal semantics of R code. In general it should be avoided, which is why <code>cpp11::writable</code> classes always copy their data when constructed. However if you are positive in-place modification is necessary for your use case you can use the move constructor to do this. <div class="sourceCode" id="cb16"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb16-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb16-2" tabindex="-1"></a> <a href="#cb16-3" tabindex="-1"></a>[[cpp11::register]] <a href="#cb16-4" tabindex="-1"></a>void add_one(cpp11::sexp x_sexp) { <a href="#cb16-5" tabindex="-1"></a> cpp11::writable::integers x(std::move(x_sexp.data())); <a href="#cb16-6" tabindex="-1"></a> for (auto&& value : x) { <a href="#cb16-7" tabindex="-1"></a> ++value; <a href="#cb16-8" tabindex="-1"></a> } <a href="#cb16-9" tabindex="-1"></a>}</code></pre></div> <div class="sourceCode" id="cb17"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb17-1" tabindex="-1"></a>x <- c(1L, 2L, 3L, 4L) <a href="#cb17-2" tabindex="-1"></a>.Internal(inspect(x)) <a href="#cb17-3" tabindex="-1"></a>#> @1284b7608 13 INTSXP g0c2 [REF(2)] (len=4, tl=0) 1,2,3,4 <a href="#cb17-4" tabindex="-1"></a>add_one(x) <a href="#cb17-5" tabindex="-1"></a>.Internal(inspect(x)) <a href="#cb17-6" tabindex="-1"></a>#> @1284b7608 13 INTSXP g0c2 [REF(6)] (len=4, tl=0) 2,3,4,5 <a href="#cb17-7" tabindex="-1"></a>x <a href="#cb17-8" tabindex="-1"></a>#> [1] 2 3 4 5</code></pre></div> </div> <div id="should-i-call-cpp11unwind_protect-manually" class="section level4"> <h4>15. Should I call <code>cpp11::unwind_protect()</code> manually?</h4> <code>cpp11::unwind_protect()</code> is cpp11’s way of safely calling R’s C API. In short, it allows you to run a function that might throw an R error, catch the <code>longjmp()</code> of that error, promote it to an exception that is thrown and caught by a try/catch that cpp11 sets up for you at <code>.Call()</code> time (which allows destructors to run), and finally tells R to continue unwinding the stack now that the C++ objects have had a chance to destruct as needed. Since <code>cpp11::unwind_protect()</code> takes an arbitrary function, you may be wondering if you should use it for your own custom needs. In general, we advise against this because this is an extremely advanced feature that is prone to subtle and hard to debug issues. <div id="destructors" class="section level5"> <h5>Destructors</h5> The following setup for <code>test_destructor_ok()</code> with a manual call to <code>unwind_protect()</code> would work: <div class="sourceCode" id="cb18"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb18-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb18-2" tabindex="-1"></a> <a href="#cb18-3" tabindex="-1"></a>class A { <a href="#cb18-4" tabindex="-1"></a> public: <a href="#cb18-5" tabindex="-1"></a> ~A(); <a href="#cb18-6" tabindex="-1"></a>}; <a href="#cb18-7" tabindex="-1"></a> <a href="#cb18-8" tabindex="-1"></a>A::~A() { <a href="#cb18-9" tabindex="-1"></a> Rprintf("hi from the destructor!"); <a href="#cb18-10" tabindex="-1"></a>} <a href="#cb18-11" tabindex="-1"></a> <a href="#cb18-12" tabindex="-1"></a>[[cpp11::register]] <a href="#cb18-13" tabindex="-1"></a>void test_destructor_ok() { <a href="#cb18-14" tabindex="-1"></a> A a{}; <a href="#cb18-15" tabindex="-1"></a> cpp11::unwind_protect([&] { <a href="#cb18-16" tabindex="-1"></a> Rf_error("oh no!"); <a href="#cb18-17" tabindex="-1"></a> }); <a href="#cb18-18" tabindex="-1"></a>} <a href="#cb18-19" tabindex="-1"></a> <a href="#cb18-20" tabindex="-1"></a>[[cpp11::register]] <a href="#cb18-21" tabindex="-1"></a>void test_destructor_bad() { <a href="#cb18-22" tabindex="-1"></a> cpp11::unwind_protect([&] { <a href="#cb18-23" tabindex="-1"></a> A a{}; <a href="#cb18-24" tabindex="-1"></a> Rf_error("oh no!"); <a href="#cb18-25" tabindex="-1"></a> }); <a href="#cb18-26" tabindex="-1"></a>}</code></pre></div> <div class="sourceCode" id="cb19"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb19-1" tabindex="-1"></a>test_destructor_ok() <a href="#cb19-2" tabindex="-1"></a>#> Error: oh no! <a href="#cb19-3" tabindex="-1"></a>#> hi from the destructor!</code></pre></div> But if you happen to move <code>a</code> into the <code>unwind_protect()</code>, then it won’t be destructed, and you’ll end up with a memory leak at best, and a much more sinister issue if your destructor is important: <div class="sourceCode" id="cb20"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb20-1" tabindex="-1"></a>test_destructor_bad() <a href="#cb20-2" tabindex="-1"></a>#> Error: oh no!</code></pre></div> In general, the only code that can be called within <code>unwind_protect()</code> is “pure” C code or C++ code that only uses POD (plain-old-data) types and no exceptions. If you mix complex C++ objects with R’s C API within <code>unwind_protect()</code>, then any R errors will result in a jump that prevents your destructors from running. </div> <div id="nested-unwind_protect" class="section level5"> <h5>Nested <code>unwind_protect()</code></h5> Another issue that can arise has to do with nested calls to <code>unwind_protect()</code>. It is very hard (if not impossible) to end up with invalidly nested <code>unwind_protect()</code> calls when using the typical cpp11 API, but you can manually create a scenario like the following: <div class="sourceCode" id="cb21"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb21-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb21-2" tabindex="-1"></a> <a href="#cb21-3" tabindex="-1"></a>[[cpp11::register]] <a href="#cb21-4" tabindex="-1"></a>void test_nested() { <a href="#cb21-5" tabindex="-1"></a> cpp11::unwind_protect([&] { <a href="#cb21-6" tabindex="-1"></a> cpp11::unwind_protect([&] { <a href="#cb21-7" tabindex="-1"></a> Rf_error("oh no!"); <a href="#cb21-8" tabindex="-1"></a> }); <a href="#cb21-9" tabindex="-1"></a> }); <a href="#cb21-10" tabindex="-1"></a>}</code></pre></div> If you were to run <code>test_nested()</code> from R, it would likely crash or hang your R session due to the following chain of events: <ul> <li><code>test_nested()</code> sets up a try/catch to catch unwind exceptions</li> <li>The outer <code>unwind_protect()</code> is called. It uses the C function <code>R_UnwindProtect()</code> to call its lambda function.</li> <li>The inner <code>unwind_protect()</code> is called. It again uses <code>R_UnwindProtect()</code>, this time to call <code>Rf_error()</code>.</li> <li><code>Rf_error()</code> performs a <code>longjmp()</code> which is caught by the inner <code>unwind_protect()</code> and promoted to an exception.</li> <li>That exception is thrown, but because we are in the outer call to <code>R_UnwindProtect()</code> (a C function), we end up throwing that exception across C stack frames. This is undefined behavior, which is known to have caused R to crash on certain platforms.</li> </ul> You might think that you’d never do this, but the same scenario can also occur with a combination of 1 call to <code>unwind_protect()</code> combined with usage of the cpp11 API: <div class="sourceCode" id="cb22"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb22-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb22-2" tabindex="-1"></a> <a href="#cb22-3" tabindex="-1"></a>[[cpp11::register]] <a href="#cb22-4" tabindex="-1"></a>void test_hidden_nested() { <a href="#cb22-5" tabindex="-1"></a> cpp11::unwind_protect([&] { <a href="#cb22-6" tabindex="-1"></a> cpp11::stop("oh no!"); <a href="#cb22-7" tabindex="-1"></a> }); <a href="#cb22-8" tabindex="-1"></a>}</code></pre></div> Because <code>cpp11::stop()</code> (and most of the cpp11 API) uses <code>unwind_protect()</code> internally, we’ve indirectly ended up in a nested <code>unwind_protect()</code> scenario again. In general, if you must use <code>unwind_protect()</code> then you must be very careful not to use any of the cpp11 API inside of the <code>unwind_protect()</code> call. It is worth pointing out that calling out to an R function from cpp11 which then calls back into cpp11 is still safe, i.e. if the registered version of the imaginary <code>test_outer()</code> function below was called from R, then that would work: <div class="sourceCode" id="cb23"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb23-1" tabindex="-1"></a>#include <cpp11.hpp> <a href="#cb23-2" tabindex="-1"></a> <a href="#cb23-3" tabindex="-1"></a>[[cpp11::register]] <a href="#cb23-4" tabindex="-1"></a>void test_inner() { <a href="#cb23-5" tabindex="-1"></a> cpp11::stop("oh no!") <a href="#cb23-6" tabindex="-1"></a>} <a href="#cb23-7" tabindex="-1"></a> <a href="#cb23-8" tabindex="-1"></a>[[cpp11::register]] <a href="#cb23-9" tabindex="-1"></a>void test_outer() { <a href="#cb23-10" tabindex="-1"></a> auto fn = cpp11::package("mypackage")["test_inner"] <a href="#cb23-11" tabindex="-1"></a> fn(); <a href="#cb23-12" tabindex="-1"></a>}</code></pre></div> This might seem unsafe because <code>cpp11::package()</code> uses <code>unwind_protect()</code> to call the R function for <code>test_inner()</code>, which then goes back into C++ to call <code>cpp11::stop()</code>, which itself uses <code>unwind_protect()</code>, so it seems like we are in a nested scenario, but this scenario does actually work. It makes more sense if we analyze it one step at a time: <ul> <li>Call the R function for <code>test_outer()</code></li> <li>A try/catch is set up to catch unwind exceptions</li> <li>The C++ function for <code>test_outer()</code> is called</li> <li><code>cpp11::package()</code> uses <code>unwind_protect()</code> to call the R function for <code>test_inner()</code></li> <li>Call the R function for <code>test_inner()</code></li> <li>A try/catch is set up to catch unwind exceptions (this is the key!)</li> <li>The C++ function for <code>test_inner()</code> is called</li> <li><code>cpp11::stop("oh no!")</code> is called, which uses <code>unwind_protect()</code> to call <code>Rf_error()</code>, causing a <code>longjmp()</code>, which is caught by that <code>unwind_protect()</code> and promoted to an exception.</li> <li>That exception is thrown, but this time it is caught by the try/catch set up by <code>test_inner()</code> as we entered it from the R side. This prevents that exception from crossing the C++ -> C boundary.</li> <li>The try/catch calls <code>R_ContinueUnwind()</code>, which <code>longjmp()</code>s again, and now the <code>unwind_protect()</code> set up by <code>cpp11::package()</code> catches that, and promotes it to an exception.</li> <li>That exception is thrown and caught by the try/catch set up by <code>test_outer()</code>.</li> <li>The try/catch calls <code>R_ContinueUnwind()</code>, which <code>longjmp()</code>s again, and at this point we can safely let the <code>longjmp()</code> proceed to force an R error.</li> </ul> </div> </div> <div id="ok-but-i-really-want-to-call-cpp11unwind_protect-manually" class="section level4"> <h4>16. Ok but I really want to call <code>cpp11::unwind_protect()</code> manually</h4> If you’ve read the above bullet and still feel like you need to call <code>unwind_protect()</code>, then you should keep in mind the following when writing the function to unwind-protect: <ul> <li>