blob: b70df8ac4fa27b22e950a8e4b405445d8f2f289e [file] [log] [blame]
<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><meta name="description" content="The nanoarrow_schema,
nanoarrow_array,
and nanoarrow_array_stream classes are
represented in R as external pointers (EXTPTRSXP). When these objects
go out of scope (i.e., when they are garbage collected or shortly
thereafter), the underlying object's release() callback is called if
the underlying pointer is non-null and if the release() callback is
non-null."><title>Danger zone: low-level pointer operations — nanoarrow_pointer_is_valid • nanoarrow</title><script src="../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><link href="../deps/bootstrap-5.3.1/bootstrap.min.css" rel="stylesheet"><script src="../deps/bootstrap-5.3.1/bootstrap.bundle.min.js"></script><!-- Font Awesome icons --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous"><!-- bootstrap-toc --><script src="https://cdn.jsdelivr.net/gh/afeld/bootstrap-toc@v1.0.1/dist/bootstrap-toc.min.js" integrity="sha256-4veVQbu7//Lk5TSmc7YV48MxtMy98e26cf5MrgZYnwo=" crossorigin="anonymous"></script><!-- headroom.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script><!-- clipboard.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.11/clipboard.min.js" integrity="sha512-7O5pXpc0oCRrxk8RUfDYFgn0nO1t+jLuIOQdOMRp4APB7uZ4vSjspzp5y6YDtDs4VzUSTbWzBFZ/LKJhnyFOKw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><!-- search --><script src="https://cdnjs.cloudflare.com/ajax/libs/fuse.js/6.4.6/fuse.js" integrity="sha512-zv6Ywkjyktsohkbp9bb45V6tEMoWhzFzXis+LrMehmJZZSys19Yxf1dopHx7WzIKxr5tK2dVcYmaCk2uqdjF4A==" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/autocomplete.js/0.38.0/autocomplete.jquery.min.js" integrity="sha512-GU9ayf+66Xx2TmpxqJpliWbT5PiGYxpaG8rfnBEk1LL8l1KGkRShhngwdXK1UgqhAzWpZHSiYPc09/NwDQIGyg==" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/mark.min.js" integrity="sha512-5CYOlHXGh6QpOFA/TeTylKLWfB3ftPsde7AnmhuitiTX4K5SqCLBeKro6sPS8ilsz1Q4NRx3v8Ko2IBiszzdww==" crossorigin="anonymous"></script><!-- pkgdown --><script src="../pkgdown.js"></script><meta property="og:title" content="Danger zone: low-level pointer operations — nanoarrow_pointer_is_valid"><meta property="og:description" content="The nanoarrow_schema,
nanoarrow_array,
and nanoarrow_array_stream classes are
represented in R as external pointers (EXTPTRSXP). When these objects
go out of scope (i.e., when they are garbage collected or shortly
thereafter), the underlying object's release() callback is called if
the underlying pointer is non-null and if the release() callback is
non-null."><!-- mathjax --><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script><!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]--></head><body>
<a href="#main" class="visually-hidden-focusable">Skip to contents</a>
<nav class="navbar fixed-top navbar-light navbar-expand-lg bg-light" data-bs-theme="light"><div class="container">
<a class="navbar-brand me-2" href="../index.html">nanoarrow</a>
<small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">0.5.0.9000</small>
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div id="navbar" class="collapse navbar-collapse ms-3">
<ul class="navbar-nav me-auto"><li class="active nav-item">
<a class="nav-link" href="../reference/index.html">Reference</a>
</li>
<li class="nav-item">
<a class="nav-link" href="../news/index.html">Changelog</a>
</li>
</ul><form class="form-inline my-2 my-lg-0" role="search">
<input type="search" class="form-control me-sm-2" aria-label="Toggle navigation" name="search-input" data-search-index="../search.json" id="search-input" placeholder="Search for" autocomplete="off"></form>
<ul class="navbar-nav"><li class="nav-item">
<a class="external-link nav-link" href="https://github.com/apache/arrow-nanoarrow/" aria-label="github">
<span class="fab fa fab fa-github fa-lg"></span>
</a>
</li>
</ul></div>
</div>
</nav><div class="container template-reference-topic">
<div class="row">
<main id="main" class="col-md-9"><div class="page-header">
<img src="" class="logo" alt=""><h1>Danger zone: low-level pointer operations</h1>
<small class="dont-index">Source: <a href="https://github.com/apache/arrow-nanoarrow/blob/main/r/R/pointers.R" class="external-link"><code>R/pointers.R</code></a></small>
<div class="d-none name"><code>nanoarrow_pointer_is_valid.Rd</code></div>
</div>
<div class="ref-description section level2">
<p>The <a href="as_nanoarrow_schema.html">nanoarrow_schema</a>,
<a href="as_nanoarrow_array.html">nanoarrow_array</a>,
and <a href="as_nanoarrow_array_stream.html">nanoarrow_array_stream</a> classes are
represented in R as external pointers (<code>EXTPTRSXP</code>). When these objects
go out of scope (i.e., when they are garbage collected or shortly
thereafter), the underlying object's <code>release()</code> callback is called if
the underlying pointer is non-null and if the <code>release()</code> callback is
non-null.</p>
</div>
<div class="section level2">
<h2 id="ref-usage">Usage<a class="anchor" aria-label="anchor" href="#ref-usage"></a></h2>
<div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">nanoarrow_pointer_is_valid</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
<span></span>
<span><span class="fu">nanoarrow_pointer_addr_dbl</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
<span></span>
<span><span class="fu">nanoarrow_pointer_addr_chr</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
<span></span>
<span><span class="fu">nanoarrow_pointer_addr_pretty</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
<span></span>
<span><span class="fu">nanoarrow_pointer_release</span><span class="op">(</span><span class="va">ptr</span><span class="op">)</span></span>
<span></span>
<span><span class="fu">nanoarrow_pointer_move</span><span class="op">(</span><span class="va">ptr_src</span>, <span class="va">ptr_dst</span><span class="op">)</span></span>
<span></span>
<span><span class="fu">nanoarrow_pointer_export</span><span class="op">(</span><span class="va">ptr_src</span>, <span class="va">ptr_dst</span><span class="op">)</span></span>
<span></span>
<span><span class="fu">nanoarrow_allocate_schema</span><span class="op">(</span><span class="op">)</span></span>
<span></span>
<span><span class="fu">nanoarrow_allocate_array</span><span class="op">(</span><span class="op">)</span></span>
<span></span>
<span><span class="fu">nanoarrow_allocate_array_stream</span><span class="op">(</span><span class="op">)</span></span>
<span></span>
<span><span class="fu">nanoarrow_pointer_set_protected</span><span class="op">(</span><span class="va">ptr_src</span>, <span class="va">protected</span><span class="op">)</span></span></code></pre></div>
</div>
<div class="section level2">
<h2 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#arguments"></a></h2>
<dl><dt>ptr, ptr_src, ptr_dst</dt>
<dd><p>An external pointer to a <code>struct ArrowSchema</code>,
<code>struct ArrowArray</code>, or <code>struct ArrowArrayStream</code>.</p></dd>
<dt>protected</dt>
<dd><p>An object whose scope must outlive that of <code>ptr</code>. This is
useful for array streams since at least two specifications involving the
array stream specify that the stream is only valid for the lifecycle of
another object (e.g., an AdbcStatement or OGRDataset).</p></dd>
</dl></div>
<div class="section level2">
<h2 id="value">Value<a class="anchor" aria-label="anchor" href="#value"></a></h2>
<ul><li><p><code>nanoarrow_pointer_is_valid()</code> returns TRUE if the pointer is non-null
and has a non-null release callback.</p></li>
<li><p><code>nanoarrow_pointer_addr_dbl()</code> and <code>nanoarrow_pointer_addr_chr()</code> return
pointer representations that may be helpful to facilitate moving or
exporting nanoarrow objects to other libraries.</p></li>
<li><p><code>nanoarrow_pointer_addr_pretty()</code> gives a pointer representation suitable
for printing or error messages.</p></li>
<li><p><code>nanoarrow_pointer_release()</code> returns <code>ptr</code>, invisibly.</p></li>
<li><p><code>nanoarrow_pointer_move()</code> and <code>nanoarrow_pointer_export()</code> reeturn
<code>ptr_dst</code>, invisibly.</p></li>
<li><p><code>nanoarrow_allocate_array()</code>, <code>nanoarrow_allocate_schema()</code>, and
<code>nanoarrow_allocate_array_stream()</code> return an
<a href="as_nanoarrow_array.html">array</a>, a <a href="as_nanoarrow_schema.html">schema</a>, and an
<a href="as_nanoarrow_array_stream.html">array stream</a>, respectively.</p></li>
</ul></div>
<div class="section level2">
<h2 id="details">Details<a class="anchor" aria-label="anchor" href="#details"></a></h2>
<p>When interacting with other C Data Interface implementations, it is
important to keep in mind that the R object wrapping these pointers is
always passed by reference (because it is an external pointer) and may
be referred to by another R object (e.g., an element in a <code><a href="https://rdrr.io/r/base/list.html" class="external-link">list()</a></code> or as a
variable assigned in a user's environment). When importing a schema,
array, or array stream into nanoarrow this is not a problem: the R object
takes ownership of the lifecycle and memory is released when the R
object is garbage collected. In this case, one can use
<code>nanoarrow_pointer_move()</code> where <code>ptr_dst</code> was created using
<code>nanoarrow_allocate_*()</code>.</p>
<p>The case of exporting is more complicated and as such has a dedicated
function, <code>nanoarrow_pointer_export()</code>, that implements different logic
schemas, arrays, and array streams:</p><ul><li><p>Schema objects are (deep) copied such that a fresh copy of the schema
is exported and made the responsibility of some other C data interface
implementation.</p></li>
<li><p>Array objects are exported as a shell around the original array that
preserves a reference to the R object. This ensures that the buffers
and children pointed to by the array are not copied and that any references
to the original array are not invalidated.</p></li>
<li><p>Array stream objects are moved: the responsibility for the object is
transferred to the other C data interface implementation and any
references to the original R object are invalidated. Because these
objects are mutable, this is typically what you want (i.e., you should
not be pulling arrays from a stream accidentally from two places).</p></li>
</ul><p>If you know the lifecycle of your object (i.e., you created the R object
yourself and never passed references to it elsewhere), you can slightly
more efficiently call <code>nanoarrow_pointer_move()</code> for all three pointer
types.</p>
</div>
</main><aside class="col-md-3"><nav id="toc"><h2>On this page</h2>
</nav></aside></div>
<footer><div class="pkgdown-footer-left">
<p>Developed by Dewey Dunnington, Apache Arrow.</p>
</div>
<div class="pkgdown-footer-right">
<p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.0.9.</p>
</div>
</footer></div>
</body></html>