Mercurial > pub > dyncall > dyncall

comparison dyncallback/dyncallback.3 @ 544:111236b31c75

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
- C++ non-trivial aggregate-by-value handling: * dyncallback support for dcbArgAggr() * better doc
author Tassilo Philipp
date Tue, 31 May 2022 18:25:13 +0200
parents 71c884e610f0
children fd7426080105
comparison
equal deleted inserted replaced
543:781b308aa320 544:111236b31c75
58 .Fn dcbArgFloat "DCArgs * p" 58 .Fn dcbArgFloat "DCArgs * p"
59 .Ft DCdouble 59 .Ft DCdouble
60 .Fn dcbArgDouble "DCArgs * p" 60 .Fn dcbArgDouble "DCArgs * p"
61 .Ft DCpointer 61 .Ft DCpointer
62 .Fn dcbArgPointer "DCArgs * p" 62 .Fn dcbArgPointer "DCArgs * p"
63 .Ft void 63 .Ft DCpointer
64 .Fn dcbArgAggr "DCArgs * p" "DCpointer target" 64 .Fn dcbArgAggr "DCArgs * p" "DCpointer target"
65 .Ft void 65 .Ft void
66 .Fn dcbReturnAggr "DCArgs * args" "DCValue * result" "DCpointer ret" 66 .Fn dcbReturnAggr "DCArgs * args" "DCValue * result" "DCpointer ret"
67 .Sh DESCRIPTION 67 .Sh DESCRIPTION
68 The 68 The
101 parameter, meaning it can only be used for callbacks that do not use any 101 parameter, meaning it can only be used for callbacks that do not use any
102 aggregate by value. 102 aggregate by value.
103 .Pp 103 .Pp
104 .Sy NOTE: 104 .Sy NOTE:
105 C++ non-trivial aggregates (check with the std::is_trivial type trait) do not 105 C++ non-trivial aggregates (check with the std::is_trivial type trait) do not
106 use any aggregate descriptions, so the respective pointers in the provided 106 use aggregate descriptions, so the respective pointers in the provided array
107 array must be NULL. See 107 must be NULL. See
108 .Xr dyncall 3 108 .Xr dyncall 3
109 for more information on C++ non-trivial aggregates. 109 for more information on C++ non-trivial aggregates.
110 .Pp 110 .Pp
111 Use the pointer returned by 111 Use the pointer returned by
112 .Fn dcbNewCallback* 112 .Fn dcbNewCallback*
113 as argument in functions requiring a callback function pointer. 113 as argument in functions requiring a callback function pointer.
114 .Pp 114 .Pp
115 .Fn dcbInitCallback 115 .Fn dcbInitCallback
116 and 116 and
117 .Fn dcbInitCallback2 117 .Fn dcbInitCallback2
118 (re)initializes the callback object. For a description of its parameters, see 118 (re)initialize the callback object. For a description of their parameters, see
119 .Fn dcbNewCallback* . 119 .Fn dcbNewCallback* .
120 .Pp 120 .Pp
121 .Fn dcbFreeCallback 121 .Fn dcbFreeCallback
122 destroys and frees the callback handler. 122 destroys and frees the callback handler.
123 .Pp 123 .Pp
142 functions to iterate over the arguments passed to the callback, and 142 functions to iterate over the arguments passed to the callback, and
143 .Ar result 143 .Ar result
144 is a pointer to an object used to store the callback's return value (output, to 144 is a pointer to an object used to store the callback's return value (output, to
145 be set by the handler). Finally, 145 be set by the handler). Finally,
146 .Ar userdata 146 .Ar userdata
147 is a pointer to some user defined data that can be set when creating or 147 is the user defined data pointer set when creating or (re)initializing the
148 (re)initializing the callback object. 148 callback object.
149 The handler itself must return a signature character (see manual or 149 The handler itself must return a signature character (see manual or
150 dyncall_signature.h for format) specifying the data type of 150 dyncall_signature.h for format) specifying the data type of
151 .Ar result . 151 .Ar result .
152 .Pp 152 .Pp
153 Retrieving aggregates from the generic handler's 153 Retrieving aggregates by value from the generic handler's
154 .Ar args 154 .Ar args
155 argument can be done via 155 argument can be done via
156 .Fn dcbArgAggr , 156 .Fn dcbArgAggr ,
157 where 157 where
158 .Ar target 158 .Ar target
159 must point to memory large enough for the aggregate to be copied to. 159 must point to memory large enough for the aggregate to be copied to,
160 .Pp 160 .Sy iff
161 To return an aggregate by value, a helper function 161 the aggregate is trivial (see below for non-trivial C++ aggregates), in which case
162 .Ar target
163 is returned.
164 .Pp
165 To return a trivial aggregate by value, a helper function
162 .Fn dcbReturnAggr 166 .Fn dcbReturnAggr
163 needs to be used in order to correctly place the aggregate pointed to by 167 needs to be used in order to correctly place the aggregate pointed to by
164 .Ar ret 168 .Ar ret
165 into 169 into
166 .Ar result , 170 .Ar result ,
167 then let the generic handler return DC_SIGCHAR_AGGREGATE. 171 then let the generic handler return DC_SIGCHAR_AGGREGATE.
172 .Pp
173 Retrieving or returning C++ non-trivial aggregates (check with the
174 std::is_trivial type trait) is done differently, as dyncall cannot know how to
175 do this copy and the C++ ABI handles those differently:
176 .Pp
177 When retrieving a C++ non-trivial aggregate via
178 .Fn dcbArgAggr ,
179 .Ar target
180 is ignored, and a pointer to the non-trivial aggregate is returned (the user
181 should then do a local copy).
182 To return a C++ non-trivial aggregate by value via
183 .Fn dcbReturnAggr ,
184 pass NULL for
185 .Ar ret ,
186 which will make
187 .Ar result->p
188 point to (implicit, caller-provided) memory where the aggregate should be
189 copied to.
190
168 .Sh EXAMPLE 191 .Sh EXAMPLE
169 Let's say, we want to create a callback object and call it. For simplicity, this 192 Let's say, we want to create a callback object and call it. For simplicity, this
170 example will omit passing it as a function pointer to a function (e.g. compar 193 example will omit passing it as a function pointer to a function (e.g. compar
171 in qsort(), etc.) and demonstrate calling it, directly. First, we need to define 194 in qsort(), etc.) and demonstrate calling it, directly. First, we need to define
172 our callback handler - the following handler illustrates how to access the passed- 195 our callback handler - the following handler illustrates how to access the passed-