危险区域：低级指针操作

在 R 中，nanoarrow_schema、nanoarrow_array 和 nanoarrow_array_stream 类被表示为外部指针 (EXTPTRSXP)。当这些对象超出范围（即，当它们被垃圾回收或之后不久）时，如果底层指针非空，并且如果 release() 回调非空，则底层对象的 release() 回调将被调用。

用法

nanoarrow_pointer_is_valid(ptr)

nanoarrow_pointer_addr_dbl(ptr)

nanoarrow_pointer_addr_chr(ptr)

nanoarrow_pointer_addr_pretty(ptr)

nanoarrow_pointer_release(ptr)

nanoarrow_pointer_move(ptr_src, ptr_dst)

nanoarrow_pointer_export(ptr_src, ptr_dst)

nanoarrow_allocate_schema()

nanoarrow_allocate_array()

nanoarrow_allocate_array_stream()

nanoarrow_pointer_set_protected(ptr_src, protected)

参数

ptr、ptr_src、ptr_dst

指向 struct ArrowSchema、struct ArrowArray 或 struct ArrowArrayStream 的外部指针。

protected

其作用域必须超过 ptr 作用域的对象。这对于数组流很有用，因为至少有两个涉及数组流的规范指定流仅在另一个对象的生命周期内有效（例如，AdbcStatement 或 OGRDataset）。

返回值

• nanoarrow_pointer_is_valid() 返回 TRUE，如果指针非空并且具有非空的释放回调。

• nanoarrow_pointer_addr_dbl() 和 nanoarrow_pointer_addr_chr() 返回指针表示，这可能有助于促进将 nanoarrow 对象移动或导出到其他库。

• nanoarrow_pointer_addr_pretty() 提供适合打印或错误消息的指针表示。

• nanoarrow_pointer_release() 返回 ptr，不可见。

• nanoarrow_pointer_move() 和 nanoarrow_pointer_export() 返回 ptr_dst，不可见。

• nanoarrow_allocate_array()、nanoarrow_allocate_schema() 和 nanoarrow_allocate_array_stream() 分别返回 数组、模式 和 数组流。

详情

与其他 C 数据接口实现交互时，务必牢记包装这些指针的 R 对象始终通过引用传递（因为它是一个外部指针），并且可能被另一个 R 对象引用（例如，list() 中的元素或在用户环境中分配的变量）。将模式、数组或数组流导入 nanoarrow 时，这不成问题：R 对象将接管生命周期，并在 R 对象被垃圾回收时释放内存。在这种情况下，可以使用 nanoarrow_pointer_move()，其中 ptr_dst 使用 nanoarrow_allocate_*() 创建。

导出情况更为复杂，因此有一个专门的函数 nanoarrow_pointer_export() 用于实现不同的逻辑模式、数组和数组流。

• 模式对象被（深度）复制，以便导出模式的新副本，并由其他 C 数据接口实现负责。

• 数组对象被导出为原始数组周围的 shell，该 shell 保留对 R 对象的引用。这确保了数组指向的缓冲区和子级不会被复制，并且对原始数组的任何引用都不会失效。

• 数组流对象被移动：对象的所有权被转移到其他 C 数据接口实现，并且对原始 R 对象的任何引用都将失效。由于这些对象是可变的，这通常是你想要的（即，你不应该意外地从两个地方拉取数组流）。

如果你知道对象的生命周期（即，你创建了 R 对象并且从未将引用传递给其他地方），你可以对所有三种指针类型稍微更高效地调用 nanoarrow_pointer_move()。