annotate R/rdc/man/rdc.Rd @ 66:7a61dd082341 default tip

pydc: - fix double free triggered by capsule destructor, when freeing pydc and callback objects, manually
author Tassilo Philipp
date Fri, 24 May 2024 18:16:29 +0200
parents 0cfcc391201f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
1 \name{rdc}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
2 \alias{rdcLoad}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
3 \alias{rdcFree}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
4 \alias{rdcFind}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
5 \alias{rdcCall}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
6 \alias{rdcPath}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
7 \alias{rdcUnpath}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
8 \alias{rdcShowPath}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
9 \alias{rdcUnpack1}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
10 \alias{rdcDataPtr}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
11 \title{invoke dynamic calls to foreign code}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
12 \description{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
13 Invoke foreign function calls with support for loading modules and resolving symbols.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
14 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
15 \usage{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
16 libhandle <- rdcLoad(libpath)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
17 rdcFree(libhandle)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
18 funcptr <- rdcFind(libhandle, symbol)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
19 result <- rdcCall(funcptr, signature, ...)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
20 rdcPath(addpath)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
21 rdcUnpath(delpath)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
22 rdcShowPath()
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
23 rdcUnpack1(object, offset, sigchar)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
24 rdcDataPtr(object, offset = 0)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
25 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
26
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
27 \arguments{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
28 \item{libpath}{a file path to dynamic linked library(DLL).}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
29 \item{libhandle}{an external pointer representing an operating-system specific handle to an opened DLL.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
30 \item{symbol}{a character string, specifying a function name symbol in a DLL.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
31 \item{funcptr}{an external pointer representing a pointer to function resolved by a symbol}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
32 \item{signature}{a character string specifying the argument and return type of a function call, see Details below for more information.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
33 \item{addpath,delpath}{a directory path from where dynamic linked libraries should be loaded.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
34 \item{object}{An atomic object (scalar, vector, matrix or array).}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
35 \item{offset}{An integer specifying an offset from the start of the linear data memory in bytes.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
36 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
37
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
38 \details{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
39 The rdc package provides tools to establish flexible function calls to low-level precompiled code.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
40 It is more flexible than \code{\link{.C}} and has the same type-unsafety dangers.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
41 One can make arbitrary C (and C++ member-) function calls.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
42 The language binding was designed to help write glue code to low-level C libraries in R (if the target library function is compatible with
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
43 the supported typeset and calling convention).
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
44 It makes use of signature strings to specify
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
45 the function prototyp to call.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
46 to providing a thin binding layer between the core
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
47 dyncall library and the R programming language.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
48
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
49 The loading and unloading of code modules (*.DLL files on windows, *.dylib files on darwin and *.so files on other *nix flavour OSs)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
50 is done using rdcLoad, similar to \code{\link{dyn.load}}. While \code{\link{dyn.load}} loads a DLL to the R run-time process,
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
51 rdcLoad returns the module handle as an external pointer.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
52
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
53 Symbol lookup is done using \code{rdcFind} and returns an external pointer pointing to the foreign function.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
54
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
55 The \code{rdcCall} function does invoke the function call.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
56 It requires the \code{signature} character string argument, which consists of a series of type codes (given as ordinary characters) to
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
57 specify the argument types and the expected return type of the foreign function call which are separated by an ')' character.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
58
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
59 \deqn{sigchar_{arg_0} sigchar_{arg_1} \ldots ')' sigchar_{return}}{<sigchar-arg0> <sigchar-arg1> \ldots ')' <sigchar-return>}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
60
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
61 A signature character encodes the C type at the given argument position or return-type.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
62
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
63 \tabular{cll}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
64 Signature char \tab C type \tab accepted R data types\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
65 \sQuote{B} \tab \code{bool} \tab coerced to logical vector, first item\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
66 \sQuote{c} \tab \code{char} \tab not yet implemented\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
67 \sQuote{s} \tab \code{short} \tab not yet implemented\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
68 \sQuote{i} \tab \code{int} \tab coerced to integer vector, first item\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
69 \sQuote{l} \tab \code{long} \tab not yet implemented\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
70 \sQuote{f} \tab \code{float} \tab coerced to numeric, first item casted to float\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
71 \sQuote{d} \tab \code{double} \tab coerced to numeric, first item\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
72 \sQuote{L} \tab \code{long long} \tab coerced to numeric, first item casted to long long\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
73 \sQuote{p} \tab \code{void*} \tab external pointer or coerced to string vector, first item\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
74 \sQuote{S} \tab \code{char*} \tab coerced to string vector, first item\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
75 \sQuote{v} \tab \code{void} \tab no return type\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
76 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
77
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
78 The order of the arguments is left-to-right according to the C prototyp function declaration. E.g.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
79
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
80 e.g. the signature string of the function \samp{double foobar(int a, long long b, float c);} is \code{"iLf)d"}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
81
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
82 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
83 \examples{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
84
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
85 # load platform-specific standard C DLL
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
86
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
87 clibname <- "libc"
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
88 if (.Platform$OS.type == "windows") clibname <- "msvcrt"
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
89 if (.Platform$OS.type == "darwin") clibname <- "libc.dylib"
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
90
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
91 clib <- rdcLoad(clibname)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
92
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
93 # call sqrt function
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
94
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
95 sqrt.fp <- rdcFind(clib,"sqrt")
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
96 print( rdcCall(sqrt.fp, "d)d", 144) )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
97
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
98 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
99 \references{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
100 Adler, D., Philipp, T. (2008) \emph{Dyncall Library}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
101 \url{http://dyncall.org}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
102 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
103 \author {
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
104 Daniel Adler \email{dadler@uni-goettingen}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
105 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
106 \examples {
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
107 # bla
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
108
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
109 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
110 \keyword{programming::interface}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
111