Mercurial > pub > dyncall > dyncall
annotate doc/manual/manual_dyncallback_api.tex @ 533:71c884e610f0
- integration of patches from Raphael Luba, Thekla, Inc.:
* integration of aggregate-by-value (struct, union) support patch for x64 (win and sysv)
* windows/x64 asm additions to specify how stack unwinds (help for debuggers, exception handling, etc.)
* see Changelog for details
- new calling convention modes for thiscalls (platform agnostic, was specific before)
* new signature character for platform agnostic thiscalls ('*' / DC_SIGCHAR_CC_THISCALL)
- dcCallF(), dcVCallF(), dcArgF() and dcVArgF():
* added support for aggregates-by-value (wasn't part of patch)
* change that those functions don't implicitly call dcReset() anymore, which was unflexible (breaking change)
- added macros to feature test implementation for aggregate-by-value and syscall support
- changed libdyncall_s.lib and libdyncallback_s.lib order in callback test makefiles, as some toolchains are picky about order
- doc:
* man page updates to describe aggregate interface
* manual overview changes to highlight platforms with aggregate-by-value support
- test/plain: replaced tests w/ old/stale sctruct interface with new aggregate one
| author | Tassilo Philipp |
|---|---|
| date | Thu, 21 Apr 2022 13:35:47 +0200 |
| parents | 17287342e273 |
| children |
| rev | line source |
|---|---|
| 467 | 1 %////////////////////////////////////////////////////////////////////////////// |
| 2 % | |
|
533
71c884e610f0
- integration of patches from Raphael Luba, Thekla, Inc.:
Tassilo Philipp
parents:
490
diff
changeset
|
3 % Copyright (c) 2007,2013-2022 Daniel Adler <dadler@uni-goettingen.de>, |
|
71c884e610f0
- integration of patches from Raphael Luba, Thekla, Inc.:
Tassilo Philipp
parents:
490
diff
changeset
|
4 % Tassilo Philipp <tphilipp@potion-studios.com> |
| 467 | 5 % |
| 6 % Permission to use, copy, modify, and distribute this software for any | |
| 7 % purpose with or without fee is hereby granted, provided that the above | |
| 8 % copyright notice and this permission notice appear in all copies. | |
| 9 % | |
| 10 % THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
| 11 % WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
| 12 % MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
| 13 % ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
| 14 % WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
| 15 % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
| 16 % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
| 17 % | |
| 18 %////////////////////////////////////////////////////////////////////////////// | |
| 19 | |
| 20 \section{\emph{Dyncallback} C library API} | |
| 21 | |
| 490 | 22 See the dyncallback(3) manpage for more information. |
| 467 | 23 |
| 490 | 24 %@@@ removed, as manpages are more precise and up to date -------------------> |
| 25 % | |
| 26 %This library extends \product{dyncall} with function callback support, allowing | |
| 27 %the user to dynamically create a callback object that can be called directly, | |
| 28 %or passed to functions expecting a function-pointer as argument.\\ | |
| 29 %\\ | |
| 30 %Invoking a \product{dyncallback} calls into a user-defined unified handler that | |
| 31 %permits iteration and thus dynamic handling over the called-back-function's | |
| 32 %parameters.\\ | |
| 33 %\\ | |
| 34 %The flexibility is constrained by the set of supported types, though.\\ | |
| 35 %\\ | |
| 36 %For style conventions and supported types, see \product{dyncall} API section. | |
| 37 %In order to use \product{dyncallback}, include {\tt "dyncall\_callback.h"}. | |
| 38 % | |
| 39 %\subsection{Callback Object} | |
| 40 % | |
| 41 %The \emph{Callback Object} is the core component to this library. | |
| 42 % | |
| 43 %\paragraph{Types} | |
| 44 % | |
| 45 %\begin{lstlisting}[language=c] | |
| 46 %typedef struct DCCallback DCCallback; | |
| 47 %\end{lstlisting} | |
| 48 % | |
| 49 %\paragraph{Details} | |
| 50 %The \emph{Callback Object} is an object that mimics a fully typed function | |
| 51 %call to another function (a generic callback handler, in this case).\\ | |
| 52 %\\ | |
| 53 %This means, a pointer to this object is passed to a function accepting a pointer | |
| 54 %to a callback function \emph{as the very callback function pointer itself}. | |
| 55 %Or, if called directly, cast a pointer to this object to a function pointer and | |
| 56 %issue a call. | |
| 57 % | |
| 58 % | |
| 59 %\subsection{Allocation} | |
| 60 % | |
| 61 %\paragraph{Functions} | |
| 62 % | |
| 63 %\begin{lstlisting}[language=c] | |
| 64 %DCCallback* dcbNewCallback(const DCsigchar* signature, | |
| 65 % DCCallbackHandler* funcptr, | |
| 66 % void* userdata, | |
| 67 % DCaggr** aggrs); | |
| 68 %void dcbFreeCallback(DCCallback* pcb); | |
| 69 %\end{lstlisting} | |
| 70 % | |
| 71 %\lstinline{dcbNewCallback} creates and initializes a new \emph{Callback} object, | |
| 72 %where \lstinline{signature} is the needed function signature (format is the | |
| 73 %one outlined in the language bindings-section of this manual, see Table \ref{sigchar}) | |
| 74 %of the function to mimic, \lstinline{funcptr} is a pointer to a callback handler, | |
| 75 %and \lstinline{userdata} a pointer to custom data that might be useful in the | |
| 76 %handler. | |
| 77 %Use \lstinline{dcbFreeCallback} to destroy the \emph{Callback} object.\\ | |
| 78 %\\ | |
| 79 %As with \capi{dcNewCallVM}/\capi{dcFree}, this will allocate memory using the | |
| 80 %system allocators or custom overrides. | |
| 81 % | |
| 82 % | |
| 83 %\subsection{Callback handler} | |
| 84 % | |
| 85 %The unified callback handler's declaration used when creating a \capi{DCCallback} | |
| 86 %is: | |
| 87 % | |
| 88 %\begin{lstlisting} | |
| 89 %DCsigchar cbHandler(DCCallback* cb, | |
| 90 % DCArgs* args, | |
| 91 % DCValue* result, | |
| 92 % void* userdata); | |
| 93 %\end{lstlisting} | |
| 94 % | |
| 95 %\capi{cb} is a pointer to the \capi{DCCallback} object in use, \capi{args} allows | |
| 96 %for dynamic iteration over the called-back-function's arguments (input) and | |
| 97 %\capi{result} is a pointer to a \capi{DCValue} object in order to store the | |
| 98 %callback's return value (output, to be set by handler).\\ | |
| 99 %Finally, \capi{userdata} is a pointer to some user defined data that can be | |
| 100 %set when creating the callback object. | |
| 101 %The handler itself returns a signature character (see Table \ref{sigchar}) specifying the | |
| 102 %data type used for \capi{result}. | |
| 103 % |