dyncall: dyncallback/dyncallback.3 annotate

annotate dyncallback/dyncallback.3 @ 544:111236b31c75

- 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

rev	line source
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	1 .\" Copyright (c) 2007-2022 Daniel Adler <dadler AT uni-goettingen DOT de>,
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	2 .\" Tassilo Philipp <tphilipp AT potion-studios DOT com>
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	3 .\"
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	4 .\" Permission to use, copy, modify, and distribute this software for any
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	5 .\" purpose with or without fee is hereby granted, provided that the above
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	6 .\" copyright notice and this permission notice appear in all copies.
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	7 .\"
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	15 .\"
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	16 .Dd $Mdocdate$
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	17 .Dt dyncallback 3
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	18 .Sh NAME
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	19 .Nm dyncallback
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	20 .Nd callback interface of dyncall
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	21 .Sh SYNOPSIS
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	22 .In dyncall_callback.h
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	23 .Ft DCCallback *
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	24 .Fn dcbNewCallback "const DCsigchar * signature" "DCCallbackHandler * funcptr" "void * userdata"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	25 .Ft DCCallback *
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	26 .Fn dcbNewCallback2 "const DCsigchar * signature" "DCCallbackHandler * funcptr" "void * userdata" "DCaggr const aggrs"
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	27 .Ft void
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	28 .Fn dcbInitCallback "DCCallback * pcb" "const DCsigchar * signature" "DCCallbackHandler * funcptr" "void * userdata"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	29 .Ft void
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	30 .Fn dcbInitCallback2 "DCCallback * pcb" "const DCsigchar * signature" "DCCallbackHandler * funcptr" "void * userdata" "DCaggr const aggrs"
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	31 .Ft void
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	32 .Fn dcbFreeCallback "DCCallback * pcb"
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	33 .Ft void
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	34 .Fn dcbGetUserData "DCCallback * pcb"
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	35 .Ft DCbool
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	36 .Fn dcbArgBool "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	37 .Ft DCchar
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	38 .Fn dcbArgChar "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	39 .Ft DCshort
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	40 .Fn dcbArgShort "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	41 .Ft DCint
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	42 .Fn dcbArgInt "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	43 .Ft DClong
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	44 .Fn dcbArgLong "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	45 .Ft DClonglong
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	46 .Fn dcbArgLongLong "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	47 .Ft DCuchar
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	48 .Fn dcbArgUChar "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	49 .Ft DCushort
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	50 .Fn dcbArgUShort "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	51 .Ft DCuint
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	52 .Fn dcbArgUInt "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	53 .Ft DCulong
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	54 .Fn dcbArgULong "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	55 .Ft DCulonglong
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	56 .Fn dcbArgULongLong "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	57 .Ft DCfloat
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	58 .Fn dcbArgFloat "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	59 .Ft DCdouble
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	60 .Fn dcbArgDouble "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	61 .Ft DCpointer
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	62 .Fn dcbArgPointer "DCArgs * p"
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	63 .Ft DCpointer
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	64 .Fn dcbArgAggr "DCArgs * p" "DCpointer target"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	65 .Ft void
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	66 .Fn dcbReturnAggr "DCArgs * args" "DCValue * result" "DCpointer ret"
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	67 .Sh DESCRIPTION
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	68 The
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	69 .Nm
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	70 dyncall library has an interface to create callback objects, that can be passed
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	71 to functions as callback function pointers. In other words, a pointer to the
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	72 callback object can be "called", directly. A generic callback handler invoked
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	73 by this object then allows iterating dynamically over the arguments once called
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	74 back.
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	75 .Pp
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	76 .Fn dcbNewCallback2
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	77 creates a new callback object, where
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	78 .Ar signature
96 95f67e67feb0 - updated dyncallback.3, blurb about handler's retval signature character was outdated cslag parents: 93 diff changeset	79 is a signature string describing the function to be called back (see manual or
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	80 dyncall_signature.h for format), and
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	81 .Ar funcptr
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	82 is a pointer to a generic callback handler (see below). The signature is needed
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	83 in the generic callback handler to correctly retrieve the arguments provided by
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	84 the caller of the callback. Note that the generic handler's function
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	85 type/declaration is always the same for any callback.
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	86 .Ar userdata
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	87 is a pointer to arbitrary user data to be available in the generic callback
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	88 handler. If the callback expects aggregates (struct, union) to be passed or
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	89 returned by value, a pointer to an array of DCaggr* descriptions must be
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	90 provided (exactly one per aggregate, in the same order as in the signature) via
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	91 the
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	92 .Ar aggrs
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	93 parameter, otherwise pass NULL. This pointer must point to valid data during
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	94 callback.
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	95 .Pp
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	96 .Fn dcbNewCallback
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	97 is the same as
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	98 .Fn dcbNewCallback2 ,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	99 with an implicit NULL passed via the
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	100 .Ar aggrs
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	101 parameter, meaning it can only be used for callbacks that do not use any
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	102 aggregate by value.
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	103 .Pp
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	104 .Sy NOTE:
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	105 C++ non-trivial aggregates (check with the std::is_trivial type trait) do not
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	106 use aggregate descriptions, so the respective pointers in the provided array
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	107 must be NULL. See
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	108 .Xr dyncall 3
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	109 for more information on C++ non-trivial aggregates.
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	110 .Pp
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	111 Use the pointer returned by
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	112 .Fn dcbNewCallback*
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	113 as argument in functions requiring a callback function pointer.
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	114 .Pp
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	115 .Fn dcbInitCallback
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	116 and
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	117 .Fn dcbInitCallback2
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	118 (re)initialize the callback object. For a description of their parameters, see
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	119 .Fn dcbNewCallback* .
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	120 .Pp
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	121 .Fn dcbFreeCallback
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	122 destroys and frees the callback handler.
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	123 .Pp
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	124 .Fn dcbGetUserData
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	125 returns a pointer to the userdata passed to the callback object on creation or
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	126 (re)initialization.
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	127 .Pp
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	128 Declaration of a dyncallback handler (following function pointer declaration in
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	129 dyncall_callback.h):
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	130 .Bd -literal -offset indent
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	131 DCsigchar cbHandler(DCCallback* cb,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	132 DCArgs* args,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	133 DCValue* result,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	134 void* userdata);
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	135 .Ed
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	136 .Pp
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	137 .Ar cb
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	138 is a pointer to the DCCallback object in use,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	139 .Ar args
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	140 is to be used with the
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	141 .Fn dcbArg*
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	142 functions to iterate over the arguments passed to the callback, and
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	143 .Ar result
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	144 is a pointer to an object used to store the callback's return value (output, to
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	145 be set by the handler). Finally,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	146 .Ar userdata
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	147 is the user defined data pointer set when creating or (re)initializing the
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	148 callback object.
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	149 The handler itself must return a signature character (see manual or
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	150 dyncall_signature.h for format) specifying the data type of
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	151 .Ar result .
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	152 .Pp
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	153 Retrieving aggregates by value from the generic handler's
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	154 .Ar args
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	155 argument can be done via
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	156 .Fn dcbArgAggr ,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	157 where
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	158 .Ar target
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	159 must point to memory large enough for the aggregate to be copied to,
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	160 .Sy iff
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	161 the aggregate is trivial (see below for non-trivial C++ aggregates), in which case
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	162 .Ar target
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	163 is returned.
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	164 .Pp
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	165 To return a trivial aggregate by value, a helper function
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	166 .Fn dcbReturnAggr
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	167 needs to be used in order to correctly place the aggregate pointed to by
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	168 .Ar ret
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	169 into
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	170 .Ar result ,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	171 then let the generic handler return DC_SIGCHAR_AGGREGATE.
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	172 .Pp
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	173 Retrieving or returning C++ non-trivial aggregates (check with the
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	174 std::is_trivial type trait) is done differently, as dyncall cannot know how to
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	175 do this copy and the C++ ABI handles those differently:
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	176 .Pp
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	177 When retrieving a C++ non-trivial aggregate via
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	178 .Fn dcbArgAggr ,
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	179 .Ar target
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	180 is ignored, and a pointer to the non-trivial aggregate is returned (the user
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	181 should then do a local copy).
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	182 To return a C++ non-trivial aggregate by value via
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	183 .Fn dcbReturnAggr ,
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	184 pass NULL for
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	185 .Ar ret ,
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	186 which will make
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	187 .Ar result->p
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	188 point to (implicit, caller-provided) memory where the aggregate should be
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	189 copied to.
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	190
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	191 .Sh EXAMPLE
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	192 Let's say, we want to create a callback object and call it. For simplicity, this
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	193 example will omit passing it as a function pointer to a function (e.g. compar
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	194 in qsort(), etc.) and demonstrate calling it, directly. First, we need to define
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	195 our callback handler - the following handler illustrates how to access the passed-
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	196 in arguments:
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	197 .Bd -literal -offset indent
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	198 DCsigchar cbHandler(DCCallback* cb,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	199 DCArgs* args,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	200 DCValue* result,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	201 void* userdata)
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	202 {
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	203 int* ud = (int*)userdata;
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	204 int arg1 = dcbArgInt (args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	205 float arg2 = dcbArgFloat (args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	206 short arg3 = dcbArgShort (args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	207 double arg4 = dcbArgDouble (args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	208 long long arg5 = dcbArgLongLong(args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	209
465 e2899b4ff713 - // -> /* /, mainly for consistency (but also for a few obscure compilers) Tassilo Philipp* parents: 250 diff changeset	210 /* .. do something .. */
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	211
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	212 result->s = 1244;
96 95f67e67feb0 - updated dyncallback.3, blurb about handler's retval signature character was outdated cslag parents: 93 diff changeset	213 return 's';
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	214 }
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	215 .Ed
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	216 .Pp
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	217 Note that the return value of the handler is a signature character, not the
96 95f67e67feb0 - updated dyncallback.3, blurb about handler's retval signature character was outdated cslag parents: 93 diff changeset	218 actual return value, itself.
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	219 Now, let's call it through a DCCallback object:
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	220 .Bd -literal -offset indent
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	221 DCCallback* cb;
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	222 short result = 0;
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	223 int userdata = 1337;
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	224 cb = dcbNewCallback("ifsdl)s", &cbHandler, &userdata);
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	225
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	226 /* call the callback object */
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	227 result = ((short(*)(int, float, short, double, long long))cb)
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	228 (123, 23.f, 3, 1.82, 9909ll);
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	229
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	230 dcbFreeCallback(cb);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	231 .Ed
250 7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	232 .Sh CONFORMING TO
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	233 The dyncallback library needs at least a c99 compiler with additional support
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	234 for anonymous structs/unions (which were introduced officially in c11). Given
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	235 that those are generally supported by pretty much all major c99 conforming
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	236 compilers (as default extension), it should build fine with a c99 toolchain.
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	237 Strictly speaking, dyncall conforms to c11, though.
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	238 .Ed
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	239 .Sh SEE ALSO
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	240 .Xr dyncall 3 ,
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	241 .Xr dynload 3
93 dfde5035d410 - better, more neutral .3 SEE ALSO cslag parents: 81 diff changeset	242 and the dyncall manual (available in HTML and PDF format) for more information.
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	243 .Sh AUTHORS
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	244 .An "Daniel Adler" Aq dadler@uni-goettingen.de
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	245 .An "Tassilo Philipp" Aq tphilipp@potion-studios.com

Mercurial > pub > dyncall > dyncall

annotate dyncallback/dyncallback.3 @ 544:111236b31c75