dyncall: dyncallback/dyncallback.3 annotate

annotate dyncallback/dyncallback.3 @ 560:fd7426080105

doc

author	Tassilo Philipp
date	Sat, 03 Sep 2022 17:03:37 +0200
parents	111236b31c75
children	1d4f0f516483

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
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	106 .Sy NOTE:
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,
111236b31c75 - C++ non-trivial aggregate-by-value handling: Tassilo Philipp parents: 533 diff changeset	162 .Sy iff
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
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	193 .Sh EXAMPLE
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	194 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	195 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	196 in qsort(), etc.) and demonstrate calling it, directly. First, we need to define
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	197 our callback handler - the following handler illustrates how to access the passed-
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	198 in arguments:
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	199 .Bd -literal -offset indent
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	200 DCsigchar cbHandler(DCCallback* cb,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	201 DCArgs* args,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	202 DCValue* result,
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	203 void* userdata)
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	204 {
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	205 int* ud = (int*)userdata;
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	206 int arg1 = dcbArgInt (args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	207 float arg2 = dcbArgFloat (args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	208 short arg3 = dcbArgShort (args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	209 double arg4 = dcbArgDouble (args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	210 long long arg5 = dcbArgLongLong(args);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	211
465 e2899b4ff713 - // -> /* /, mainly for consistency (but also for a few obscure compilers) Tassilo Philipp* parents: 250 diff changeset	212 /* .. do something .. */
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	213
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	214 result->s = 1244;
96 95f67e67feb0 - updated dyncallback.3, blurb about handler's retval signature character was outdated cslag parents: 93 diff changeset	215 return 's';
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	216 }
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	217 .Ed
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	218 .Pp
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	219 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	220 actual return value, itself.
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	221 Now, let's call it through a DCCallback object:
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	222 .Bd -literal -offset indent
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	223 DCCallback* cb;
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	224 short result = 0;
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	225 int userdata = 1337;
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	226 cb = dcbNewCallback("ifsdl)s", &cbHandler, &userdata);
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	227
71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	228 /* call the callback object */
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	229 result = ((short(*)(int, float, short, double, long long))cb)
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	230 (123, 23.f, 3, 1.82, 9909ll);
533 71c884e610f0 - integration of patches from Raphael Luba, Thekla, Inc.: Tassilo Philipp parents: 465 diff changeset	231
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	232 dcbFreeCallback(cb);
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	233 .Ed
250 7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	234 .Sh CONFORMING TO
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	235 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	236 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	237 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	238 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	239 Strictly speaking, dyncall conforms to c11, though.
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc Tassilo Philipp parents: 96 diff changeset	240 .Ed
0 3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	241 .Sh SEE ALSO
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	242 .Xr dyncall 3 ,
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	243 .Xr dynload 3
93 dfde5035d410 - better, more neutral .3 SEE ALSO cslag parents: 81 diff changeset	244 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	245 .Sh AUTHORS
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	246 .An "Daniel Adler" Aq dadler@uni-goettingen.de
3e629dc19168 initial from svn dyncall-1745 Daniel Adler parents: diff changeset	247 .An "Tassilo Philipp" Aq tphilipp@potion-studios.com

Mercurial > pub > dyncall > dyncall

annotate dyncallback/dyncallback.3 @ 560:fd7426080105