eddelbuettel commented on code in PR #332: URL: https://github.com/apache/arrow-nanoarrow/pull/332#discussion_r1440913716
########## r/inst/include/nanoarrow/r.h: ########## @@ -0,0 +1,353 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +#ifndef NANOARROW_R_H_INCLUDED +#define NANOARROW_R_H_INCLUDED + +#include <R.h> +#include <Rinternals.h> + +#include <stdlib.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/// \defgroup nanoarrow-r Utilities for Arrow R extensions +/// +/// EXPERIMENTAL: The interface and lifecycle semantics described in this header +/// should be considered experimental and may change in a future version based on +/// user feedback. +/// +/// In the nanoarrow R package, an external pointer to an ArrowSchema, ArrowArray, or +/// ArrowArrayStream carries the class "nanoarrow_schema", "nanoarrow_array", or +/// "nanoarrow_array_stream" (respectively). The pointer must point to valid memory +/// or be NULL until the R external pointer object is finalized. +/// +/// nanoarrow_schema_owning_xptr(), nanoarrow_array_owning_xptr(), and +/// nanoarrow_array_stream_owning_xptr() initialize such an external pointer using +/// malloc() and a NULL initial release() callback such that it can be distinguished from +/// a pointer to an initialized value according to the Arrow C Data/Stream interface +/// documentation. This structure is intended to have a valid value initialized into it +/// using ArrowXXXMove() or by passing the pointer to a suitable exporting function. +/// +/// External pointers allocated by nanoarrow_xxxx_owning_xptr() register a finalizer +/// that will call the release() callback when its value is non-NULL and points to +/// a structure whose release() callback is also non-NULL. External pointers may also +/// manage lifecycle by declaring a strong reference to a single R object via +/// R_SetExternalPtrProtected(); however, when passing the address of an R external +/// pointer to a non-R library, the ownership of the structure must *not* have such SEXP +/// dependencies. The nanoarrow R package can wrap such an SEXP dependency into a +/// self-contained thread-safe release callback via nanoarrow_pointer_export() that +/// manages the SEXP dependency using a preserve/release mechanism similar to +/// R_PreserveObject()/ R_ReleaseObject(). +/// +/// The "tag" of an external pointer to an ArrowArray must be R_NilValue or an external +/// pointer to an ArrowSchema that may be used to interpret the pointed-to ArrowArray. The +/// "tag" of a nanoarrow external pointer to an ArrowSchema or ArrowArrayStream is +/// reserved for future use and must be R_NilValue. Review Comment: All the above is quite good and helpful, and I wish I would have had that earlier. Some of it is still a little vague (ie if this is different and distinguishable from Arrow, why is that so and where are some example use cases -- my use of nanoarrow has been to 'be like Arrow' without requiring and I do not seem alone in this). Let me chew over it some more -- but it looks like a nice step forward. So thanks for that! -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
