Mercurial > pub > dyncall > dyncall

comparison doc/manual/manual_dyncallback_api.tex @ 490:17287342e273

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
manual: - removed all API description and referred to manual instead, to avoid outdated and/or duplicated doc - cleanups and clarificaions
author Tassilo Philipp
date Sun, 20 Mar 2022 14:26:55 +0100
parents b47168dacba6
children 71c884e610f0
comparison
equal deleted inserted replaced
489:63f623bff0b9 490:17287342e273
15 % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15 % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16 % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 % 17 %
18 %////////////////////////////////////////////////////////////////////////////// 18 %//////////////////////////////////////////////////////////////////////////////
19 19
20 \clearpage
21 \section{\emph{Dyncallback} C library API} 20 \section{\emph{Dyncallback} C library API}
22 21
23 This library extends \product{dyncall} with function callback support, allowing 22 See the dyncallback(3) manpage for more information.
24 the user to dynamically create a callback object that can be called directly,
25 or passed to functions expecting a function-pointer as argument.\\
26 \\
27 Invoking a \product{dyncallback} calls into a user-defined unified handler that
28 permits iteration and thus dynamic handling over the called-back-function's
29 parameters.\\
30 \\
31 The flexibility is constrained by the set of supported types, though.\\
32 \\
33 For style conventions and supported types, see \product{dyncall} API section.
34 In order to use \product{dyncallback}, include {\tt "dyncall\_callback.h"}.
35 23
36 \subsection{Callback Object} 24 %@@@ removed, as manpages are more precise and up to date ------------------->
37 25 %
38 The \emph{Callback Object} is the core component to this library. 26 %This library extends \product{dyncall} with function callback support, allowing
39 27 %the user to dynamically create a callback object that can be called directly,
40 \paragraph{Types} 28 %or passed to functions expecting a function-pointer as argument.\\
41 29 %\\
42 \begin{lstlisting}[language=c] 30 %Invoking a \product{dyncallback} calls into a user-defined unified handler that
43 typedef struct DCCallback DCCallback; 31 %permits iteration and thus dynamic handling over the called-back-function's
44 \end{lstlisting} 32 %parameters.\\
45 33 %\\
46 \paragraph{Details} 34 %The flexibility is constrained by the set of supported types, though.\\
47 The \emph{Callback Object} is an object that mimics a fully typed function 35 %\\
48 call to another function (a generic callback handler, in this case).\\ 36 %For style conventions and supported types, see \product{dyncall} API section.
49 \\ 37 %In order to use \product{dyncallback}, include {\tt "dyncall\_callback.h"}.
50 This means, a pointer to this object is passed to a function accepting a pointer 38 %
51 to a callback function \emph{as the very callback function pointer itself}. 39 %\subsection{Callback Object}
52 Or, if called directly, cast a pointer to this object to a function pointer and 40 %
53 issue a call. 41 %The \emph{Callback Object} is the core component to this library.
54 42 %
55 43 %\paragraph{Types}
56 \subsection{Allocation} 44 %
57 45 %\begin{lstlisting}[language=c]
58 \paragraph{Functions} 46 %typedef struct DCCallback DCCallback;
59 47 %\end{lstlisting}
60 \begin{lstlisting}[language=c] 48 %
61 DCCallback* dcbNewCallback(const char* signature, 49 %\paragraph{Details}
62 DCCallbackHandler* funcptr, 50 %The \emph{Callback Object} is an object that mimics a fully typed function
63 void* userdata, 51 %call to another function (a generic callback handler, in this case).\\
64 DCaggr** aggrs); 52 %\\
65 void dcbFreeCallback(DCCallback* pcb); 53 %This means, a pointer to this object is passed to a function accepting a pointer
66 \end{lstlisting} 54 %to a callback function \emph{as the very callback function pointer itself}.
67 55 %Or, if called directly, cast a pointer to this object to a function pointer and
68 \lstinline{dcbNewCallback} creates and initializes a new \emph{Callback} object, 56 %issue a call.
69 where \lstinline{signature} is the needed function signature (format is the 57 %
70 one outlined in the language bindings-section of this manual, see Table \ref{sigchar}) 58 %
71 of the function to mimic, \lstinline{funcptr} is a pointer to a callback handler, 59 %\subsection{Allocation}
72 and \lstinline{userdata} a pointer to custom data that might be useful in the 60 %
73 handler. 61 %\paragraph{Functions}
74 Use \lstinline{dcbFreeCallback} to destroy the \emph{Callback} object.\\ 62 %
75 \\ 63 %\begin{lstlisting}[language=c]
76 As with \capi{dcNewCallVM}/\capi{dcFree}, this will allocate memory using the 64 %DCCallback* dcbNewCallback(const DCsigchar* signature,
77 system allocators or custom overrides. 65 % DCCallbackHandler* funcptr,
78 66 % void* userdata,
79 67 % DCaggr** aggrs);
80 \subsection{Callback handler} 68 %void dcbFreeCallback(DCCallback* pcb);
81 69 %\end{lstlisting}
82 The unified callback handler's declaration used when creating a \capi{DCCallback} 70 %
83 is: 71 %\lstinline{dcbNewCallback} creates and initializes a new \emph{Callback} object,
84 72 %where \lstinline{signature} is the needed function signature (format is the
85 \begin{lstlisting} 73 %one outlined in the language bindings-section of this manual, see Table \ref{sigchar})
86 char cbHandler(DCCallback* cb, 74 %of the function to mimic, \lstinline{funcptr} is a pointer to a callback handler,
87 DCArgs* args, 75 %and \lstinline{userdata} a pointer to custom data that might be useful in the
88 DCValue* result, 76 %handler.
89 void* userdata); 77 %Use \lstinline{dcbFreeCallback} to destroy the \emph{Callback} object.\\
90 \end{lstlisting} 78 %\\
91 79 %As with \capi{dcNewCallVM}/\capi{dcFree}, this will allocate memory using the
92 \capi{cb} is a pointer to the \capi{DCCallback} object in use, \capi{args} allows 80 %system allocators or custom overrides.
93 for dynamic iteration over the called-back-function's arguments (input) and 81 %
94 \capi{result} is a pointer to a \capi{DCValue} object in order to store the 82 %
95 callback's return value (output, to be set by handler).\\ 83 %\subsection{Callback handler}
96 Finally, \capi{userdata} is a pointer to some user defined data that can be 84 %
97 set when creating the callback object. 85 %The unified callback handler's declaration used when creating a \capi{DCCallback}
98 The handler itself returns a signature character (see Table \ref{sigchar}) specifying the 86 %is:
99 data type used for \capi{result}. 87 %
100 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 %