dyncall: dyncallback/dyncallback.3 annotate

annotate dyncallback/dyncallback.3 @ 579:1d4f0f516483

man pages: - dyncall(3): removal of unnecessary whitespace - dyncallback(3): added many more examples

author	Tassilo Philipp
date	Thu, 08 Sep 2022 17:36:20 +0200
parents	fd7426080105
children

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
560 fd7426080105 doc Tassilo Philipp parents: 544 diff changeset	23 .Ft typedef DCsigchar
fd7426080105 doc Tassilo Philipp parents: 544 diff changeset	24 .Fn (DCCallbackHandler) "DCCallback* pcb" "DCArgs* args" "DCValue* result" "void* userdata"
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	25 .Ft DCCallback *
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	26 .Fn dcbNewCallback "const DCsigchar * signature" "DCCallbackHandler * funcptr" "void * userdata"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	27 .Ft DCCallback *
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	28 .Fn dcbNewCallback2 "const DCsigchar * signature" "DCCallbackHandler * funcptr" "void * userdata" "DCaggr const aggrs"
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	29 .Ft void
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	30 .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	31 .Ft void
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	32 .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	33 .Ft void
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	34 .Fn dcbFreeCallback "DCCallback * pcb"
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	35 .Ft void
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	36 .Fn dcbGetUserData "DCCallback * pcb"
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	37 .Ft DCbool
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	38 .Fn dcbArgBool "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	39 .Ft DCchar
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	40 .Fn dcbArgChar "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	41 .Ft DCshort
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	42 .Fn dcbArgShort "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	43 .Ft DCint
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	44 .Fn dcbArgInt "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	45 .Ft DClong
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	46 .Fn dcbArgLong "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	47 .Ft DClonglong
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	48 .Fn dcbArgLongLong "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	49 .Ft DCuchar
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	50 .Fn dcbArgUChar "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	51 .Ft DCushort
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	52 .Fn dcbArgUShort "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	53 .Ft DCuint
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	54 .Fn dcbArgUInt "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	55 .Ft DCulong
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	56 .Fn dcbArgULong "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	57 .Ft DCulonglong
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	58 .Fn dcbArgULongLong "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	59 .Ft DCfloat
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	60 .Fn dcbArgFloat "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	61 .Ft DCdouble
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	62 .Fn dcbArgDouble "DCArgs * p"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	63 .Ft DCpointer
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	64 .Fn dcbArgPointer "DCArgs * p"
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	65 .Ft DCpointer
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	66 .Fn dcbArgAggr "DCArgs * p" "DCpointer target"
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	67 .Ft void
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	68 .Fn dcbReturnAggr "DCArgs * args" "DCValue * result" "DCpointer ret"
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	69 .Sh DESCRIPTION
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	70 The
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	71 .Nm
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	72 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	73 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	74 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	75 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	76 back.
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	77 .Pp
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	78 .Fn dcbNewCallback2
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	79 creates a new callback object, where
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	80 .Ar signature
96 95f67e67feb0 - updated dyncallback.3, blurb about handler's retval signature character was outdated cslag parents: 93 diff changeset	81 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	82 dyncall_signature.h for format), and
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	83 .Ar funcptr
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	84 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	85 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	86 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	87 type/declaration is always the same for any callback.
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	88 .Ar userdata
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	89 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	90 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	91 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	92 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	93 the
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	94 .Ar aggrs
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	95 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	96 callback.
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	97 .Pp
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	98 .Fn dcbNewCallback
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	99 is the same as
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	100 .Fn dcbNewCallback2 ,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	101 with an implicit NULL passed via the
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	102 .Ar aggrs
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	103 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	104 aggregate by value.
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	105 .Pp
579 1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	106 .Em NOTE :
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	107 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	108 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	109 must be NULL. See
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	110 .Xr dyncall 3
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	111 for more information on C++ non-trivial aggregates.
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	112 .Pp
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	113 Use the pointer returned by
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	114 .Fn dcbNewCallback*
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	115 as argument in functions requiring a callback function pointer.
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	116 .Pp
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	117 .Fn dcbInitCallback
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	118 and
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	119 .Fn dcbInitCallback2
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	120 (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	121 .Fn dcbNewCallback* .
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	122 .Pp
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	123 .Fn dcbFreeCallback
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	124 destroys and frees the callback handler.
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	125 .Pp
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	126 .Fn dcbGetUserData
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	127 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	128 (re)initialization.
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	129 .Pp
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	130 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	131 dyncall_callback.h):
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	132 .Bd -literal -offset indent
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	133 DCsigchar cbHandler(DCCallback* cb,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	134 DCArgs* args,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	135 DCValue* result,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	136 void* userdata);
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	137 .Ed
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	138 .Pp
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	139 .Ar cb
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	140 is a pointer to the DCCallback object in use,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	141 .Ar args
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	142 is to be used with the
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	143 .Fn dcbArg*
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	144 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	145 .Ar result
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	146 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	147 be set by the handler). Finally,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	148 .Ar userdata
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	149 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	150 callback object.
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	151 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	152 dyncall_signature.h for format) specifying the data type of
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	153 .Ar result .
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	154 .Pp
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	155 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	156 .Ar args
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	157 argument can be done via
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	158 .Fn dcbArgAggr ,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	159 where
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	160 .Ar target
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	161 must point to memory large enough for the aggregate to be copied to,
579 1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	162 .Em iff
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	163 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	164 .Ar target
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	165 is returned.
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	166 .Pp
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	167 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	168 .Fn dcbReturnAggr
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	169 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	170 .Ar ret
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	171 into
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	172 .Ar result ,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	173 then let the generic handler return DC_SIGCHAR_AGGREGATE.
544 111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	174 .Pp
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	175 Retrieving or returning C++ non-trivial aggregates (check with the
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	176 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	177 do this copy and the C++ ABI handles those differently:
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	178 .Pp
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	179 When retrieving a C++ non-trivial aggregate via
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	180 .Fn dcbArgAggr ,
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	181 .Ar target
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	182 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	183 should then do a local copy).
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	184 To return a C++ non-trivial aggregate by value via
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	185 .Fn dcbReturnAggr ,
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	186 pass NULL for
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	187 .Ar ret ,
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	188 which will make
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	189 .Ar result->p
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	190 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	191 copied to.
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	192
579 1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	193 .Sh EXAMPLES
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	194 .Em Note :
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	195 for simplicity, none of the examples below do any error checking. Also, none of
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	196 them pass the callback object pointer as an argument to a function doing the
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	197 respective callback (e.g.
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	198 .Ar compar
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	199 in
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	200 .Xr qsort 3 ,
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	201 etc.), but demonstrate calling it, directly, for clarity.
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	202 .Pp
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	203 Let's say, we want to create a callback object and call it. First, we need to
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	204 define our callback handler - the following handler illustrates how to access
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	205 the passed-in arguments, optional userdata, and how to return values:
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	206 .Bd -literal -offset indent
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	207 DCsigchar cbHandler(DCCallback* cb,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	208 DCArgs* args,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	209 DCValue* result,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	210 void* userdata)
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 int* ud = (int*)userdata;
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	213 int arg1 = dcbArgInt (args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	214 float arg2 = dcbArgFloat (args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	215 short arg3 = dcbArgShort (args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	216 double arg4 = dcbArgDouble (args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	217 long long arg5 = dcbArgLongLong(args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	218
465 e2899b4ff713 - // -> /* /, mainly for consistency (but also for a few obscure compilers) Tassilo Philipp* parents: 250 diff changeset	219 /* .. do something .. */
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	220
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	221 result->s = 1244;
96 95f67e67feb0 - updated dyncallback.3, blurb about handler's retval signature character was outdated cslag parents: 93 diff changeset	222 return 's';
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	223 }
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	224 .Ed
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	225 .Pp
579 1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	226 Note that the return value of the handler is a signature character, and not the
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	227 actual return value, itself. Now, let's call it through a
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	228 .Sy DCCallback
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	229 object:
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	230 .Bd -literal -offset indent
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	231 DCCallback* cb;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	232 short result = 0;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	233 int userdata = 1337;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	234 cb = dcbNewCallback("ifsdl)s", &cbHandler, &userdata);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	235
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	236 /* call the callback object */
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	237 result = ((short(*)(int, float, short, double, long long))cb)
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	238 (123, 23.f, 3, 1.82, 9909ll);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	239
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	240 dcbFreeCallback(cb);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	241 .Ed
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	242 .Ss C/trivial aggregates by-value
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	243 Onto an example calling back a function which takes an aggregate
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	244 .Em "by value"
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	245 (note that this is only available on platforms where macro
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	246 .Dv DC__Feature_AggrByVal
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	247 is defined). E.g. with the following function
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	248 .Fn f
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	249 and
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	250 .Sy struct S :
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	251 .Bd -literal -offset indent
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	252 struct S { char x[3]; double y; };
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	253 int f(struct S, float);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	254 .Ed
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	255 .Pp
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	256 the callback handler would look like:
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	257 .Bd -literal -offset indent
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	258 DCsigchar cbHandler(DCCallback* cb,
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	259 DCArgs* args,
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	260 DCValue* result,
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	261 void* userdata)
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	262 {
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	263 struct S arg1;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	264 float arg2;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	265 dcbArgAggr(args, (DCpointer)&arg1);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	266 arg2 = dcbArgFloat(args);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	267
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	268 /* ... */
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	269
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	270 result->i = 1;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	271 return 'i';
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	272 }
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	273 .Ed
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	274 .Pp
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	275 and the callback object as well as the aggregate field/layout description are
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	276 set up (and the former called back) as follows:
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	277 .Bd -literal -offset indent
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	278 struct S s = { { 56, -23, 0 }, -6.28 };
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	279 int result;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	280
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	281 DCCallback* cb;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	282
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	283 DCaggr *a = dcNewAggr(2, sizeof(struct S));
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	284 dcAggrField(a, DC_SIGCHAR_CHAR, offsetof(struct S, x), 3);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	285 dcAggrField(a, DC_SIGCHAR_DOUBLE, offsetof(struct S, y), 1);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	286 dcCloseAggr(a);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	287
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	288 /* an array of DCaggr* must be passed as last arg, with one
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	289 * entry per 'A' signature character; we got only one, here
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	290 */
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	291 cb = dcbNewCallback2("Af)v", &cbHandler, NULL, &a);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	292
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	293 /* call the callback object */
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	294 result = ((int(*)(struct S, float))cb)(s, 42.f);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	295
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	296 dcbFreeCallback(cb);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	297 dcFreeAggr(a);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	298 .Ed
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	299 .Pp
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	300 Let's extend the last example, so that the callback function also returns
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	301 .Sy struct S
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	302 .Em "by value" .
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	303 The struct definition, function declaration and handler definition would be:
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	304 .Bd -literal -offset indent
579 1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	305 /* callback function decl */
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	306 struct S f(struct S, float);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	307
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	308 struct S { char x[3]; double y; };
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	309
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	310 DCsigchar cbHandler(DCCallback* cb,
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	311 DCArgs* args,
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	312 DCValue* result,
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	313 void* userdata)
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	314 {
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	315 struct S arg1, r;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	316 float arg2;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	317 dcbArgAggr(args, (DCpointer)&arg1);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	318 arg2 = dcbArgFloat(args);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	319
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	320 /* ... */
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	321
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	322 /* use helper to write aggregate return value to result */
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	323 dcbReturnAggr(args, result, (DCpointer)&r);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	324 return 'A';
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	325 }
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	326 .Ed
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	327 .Pp
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	328 .Pp
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	329 and the callback object as well as the aggregate field/layout descriptions are
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	330 set up (and the former called back) as follows:
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	331 .Bd -literal -offset indent
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	332 struct S s = { { 33, 29, -1 }, 6.8 };
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	333 struct S result;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	334
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	335 DCCallback* cb;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	336
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	337 DCaggr *a = { dcNewAggr(2, sizeof(struct S)) };
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	338 dcAggrField(a, DC_SIGCHAR_CHAR, offsetof(struct S, x), 3);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	339 dcAggrField(a, DC_SIGCHAR_DOUBLE, offsetof(struct S, y), 1);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	340 dcCloseAggr(a);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	341
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	342 /* an array of DCaggr* must be passed as last arg, with one
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	343 * entry per 'A' signature character
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	344 */
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	345 cb = dcbNewCallback2("Af)A", &cbHandler, NULL, (DCaggr*[2]){a,a});
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	346
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	347 /* call the callback object */
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	348 result = ((struct S(*)(struct S, float))cb)(s, 42.f);
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	349
579 1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	350 dcbFreeCallback(cb);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	351 dcFreeAggr(a);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	352 .Ed
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	353 .Ss C++
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	354 In our next example, let's look at setting up a
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	355 .Sy DCCallback
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	356 object to call back a simple C++ method (illustrating the need to specify the
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	357 thiscall calling convention). If the class and method is declared as:
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	358 .Bd -literal -offset indent
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	359 class Klass {
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	360 public:
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	361 virtual void Method(float, int);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	362 };
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	363 .Ed
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	364 .Pp
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	365 the respective callback handler would be something along the lines of:
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	366 .Bd -literal -offset indent
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	367 DCsigchar cbHandler(DCCallback* cb,
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	368 DCArgs* args,
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	369 DCValue* result,
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	370 void* userdata)
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	371 {
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	372 Klass* thisptr = (Klass*)dcbArgPointer(args);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	373 float arg1 = dcbArgFloat(args);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	374 int arg2 = dcbArgInt(args);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	375
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	376 /* ... */
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	377
579 1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	378 return 'v';
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	379 }
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	380 .Ed
579 1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	381 .Pp
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	382 and the callback object would be used as follows:
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	383 .Bd -literal -offset indent
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	384 DCCallback* cb;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	385 cb = dcbNewCallback("_*pfi)v", &cbHandler, NULL);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	386
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	387 /* HACK: this is a hack just for this example to force the compiler
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	388 * generating a thiscall, below (creates a fake vtable mimicking
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	389 * Klass, setting all of its possible entries to our callback handler;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	390 */
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	391 DCpointer fakeClass[sizeof(Klass)/sizeof(DCpointer)];
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	392 for(int j=0; j<sizeof(Klass)/sizeof(DCpointer); ++j)
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	393 fakeClass[j] = &cb;
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	394
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	395 /* (this)call the callback object */
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	396 ((Klass*)&fakeClass)->Method(8, 23.f);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	397
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	398 dcbFreeCallback(cb);
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	399 .Ed
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	400 .Pp
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	401 .Em NOTE :
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	402 In a real world scenario one would figure out the precise location of the vtable entry of
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	403 .Fn Klass::Method ,
1d4f0f516483 man pages: Tassilo Philipp parents: 560 diff changeset	404 of course; the above example omits this for simplicity.
250 7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	405 .Sh CONFORMING TO
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	406 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	407 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	408 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	409 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	410 Strictly speaking, dyncall conforms to c11, though.
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	411 .Ed
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	412 .Sh SEE ALSO
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	413 .Xr dyncall 3 ,
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	414 .Xr dynload 3
93 dfde5035d410 - better, more neutral .3 SEE ALSO cslag parents: 81 diff changeset	415 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	416 .Sh AUTHORS
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	417 .An "Daniel Adler" Aq dadler@uni-goettingen.de
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	418 .An "Tassilo Philipp" Aq tphilipp@potion-studios.com

Mercurial > pub > dyncall > dyncall

annotate dyncallback/dyncallback.3 @ 579:1d4f0f516483