annotate R/rdyncall/man/struct.Rd @ 66:7a61dd082341 default tip

pydc: - fix double free triggered by capsule destructor, when freeing pydc and callback objects, manually
author Tassilo Philipp
date Fri, 24 May 2024 18:16:29 +0200
parents 0cfcc391201f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
1 \name{struct}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
2 \alias{struct}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
3 \alias{new.struct}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
4 \alias{as.struct}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
5 \alias{parseStructInfos}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
6 \alias{parseUnionInfos}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
7 \alias{$.struct}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
8 \alias{print.struct}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
9 \alias{$<-.struct}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
10 \title{Allocation and handling of foreign C aggregate data types}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
11 \description{Functions for allocation, access and registration of foreign C \code{struct} and \code{union} data type.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
12 \usage{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
13 new.struct(type)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
14 as.struct(x, type)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
15 parseStructInfos(sigs, envir=parent.frame())
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
16 parseUnionInfos(sigs, envir=parent.frame())
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
17 \S3method{$}{struct}(x, index)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
18 \S3method{$}{struct}(x, index) <- value
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
19 \S3method{print}{struct}(x, indent=0, \ldots)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
20 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
21 \arguments{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
22 \item{x}{external pointer or atomic raw vector of S3 class 'struct'.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
23 \item{type}{S3 \link{TypeInfo} Object or character string that names the structure type.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
24 \item{sigs}{character string that specifies several C struct/union type \link{signature}s.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
25 \item{envir}{the environment to install S3 type information object(s).}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
26 \item{index}{character string specifying the field name.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
27 \item{indent}{indentation level for pretty printing structures.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
28 \item{value}{value to be converted according to struct/union field type given by field index.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
29 \item{...}{additional arguments to be passed to \code{\link[base]{print}} method.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
30 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
31 \details{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
32 References to foreign C data objects are represented by objects of class 'struct'.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
33
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
34 Two reference types are supported:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
35
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
36 \itemize{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
37 \item \emph{External pointers} returned by \code{\link{.dyncall}} using a call signature with a \emph{typed pointer} return type signature
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
38 and pointers extracted as a result of \code{\link{.unpack}} and S3 \code{struct} \code{$}-operators.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
39 \item \emph{Internal objects}, memory-managed by R, are allocated by \code{new.struct}:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
40 An atomic \code{raw} storage object is returned, initialized with length equal to the byte size of the
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
41 foreign C data type.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
42 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
43
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
44 In order to access and manipulate the data fields of foreign C aggregate data objects, the \dQuote{$} and \dQuote{$<-} S3 operator methods
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
45 can be used.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
46
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
47 S3 objects of class \code{struct} have an attribute \code{struct} set to the name of a \code{\link{TypeInfo}} object, which provides the
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
48 run-time type information of a particular foreign C type.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
49
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
50 The run-time type information for foreign C \code{struct} and \code{union} types need to be registered once via
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
51 \code{parseStructInfos} and \code{parseUnionInfos} functions.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
52 The C data types are specified by \code{sigs}, a signature character string. The formats for both types are described next:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
53
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
54 \strong{Structure type signatures} describe the layout of aggregate \code{struct} C data types.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
55 Type Signatures are used within the \sQuote{field-types}. \sQuote{field-names} consists of space separated identifier names and
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
56 should match the number of fields.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
57
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
58 \tabular{c}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
59 \emph{struct-name} '\code{\{}' \emph{field-types} '\code{\}}' \emph{field-names} '\code{;}' \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
60 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
61
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
62 Here is an example of a C \code{struct} type:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
63
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
64 \preformatted{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
65 struct Rect \{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
66 signed short x, y;
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
67 unsigned short w, h;
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
68 \};
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
69 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
70
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
71 The corresponding structure type signature is:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
72
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
73 \preformatted{"Rect\{ssSS\}x y w h;"}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
74
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
75 \strong{Union type signatures} describe the components of the \code{union} C data type.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
76 Type signatures are used within the \sQuote{field-types}. \sQuote{field-names} consists of space separated identifier names and
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
77 should match the number of fields.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
78
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
79 \tabular{c}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
80 \emph{union-name} '\code{|}' \emph{field-types} '\code{\}}' \emph{field-names} '\code{;}' \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
81 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
82
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
83 Here is an example of a C \code{union} type,
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
84
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
85 \preformatted{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
86 union Value \{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
87 int anInt;
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
88 float aFloat;
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
89 struct LongValue aStruct
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
90 \};
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
91 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
92
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
93 The corresponding union type signature is:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
94
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
95 \code{"Value|if<LongValue>}anInt aFloat aStruct;"}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
96
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
97 \code{as.struct} can be used to \emph{cast} a foreign C data reference to a different type.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
98 When using an external pointer reference, this can lead quickly to a \strong{fatal R process crash} - like in C.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
99 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
100 \seealso{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
101 \code{\link{.dyncall}} for type signatures and \code{\link{TypeInfo}} for details on run-time type information S3 objects.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
102 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
103 \examples{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
104 # Specify the following foreign type:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
105 # struct Rect {
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
106 # short x, y;
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
107 # unsigned short w, h;
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
108 # }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
109 parseStructInfos("Rect{ssSS}x y w h;")
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
110 r <- new.struct(Rect)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
111 print(r)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
112 r$x <- 40
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
113 r$y <- 60
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
114 r$w <- 10
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
115 r$h <- 15
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
116 print(r)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
117 str(r)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
118 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
119 \keyword{programming}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
120 \keyword{interface}