annotate R/rdyncall/man/rdyncall.Rd @ 63:9b6cdffd30dd

- further fixes of inccorect overflow errors for int (and long on LLP64 systems) * prev commit had bugs * added overflow tests for also int, long, long long (for both, lp64 and llp64) - while at it, fixing a reference leak when not using python with utf8 caching
author Tassilo Philipp
date Sun, 19 May 2024 15:33:18 +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{rdyncall}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
2 \docType{package}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
3 \alias{rdyncall}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
4 \alias{rdyncall-package}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
5 \title{Improved Foreign Function Interface (FFI) and Dynamic Bindings to C Libraries (e.g. OpenGL) }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
6 \description{The package provides a cross-platform framework for dynamic binding of
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
7 C libraries using a flexible Foreign Function Interface (FFI).
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
8 The FFI supports almost all fundamental C types, multiple calling conventions,
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
9 symbolic access to foreign C struct/union data types and wrapping of R functions
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
10 as C callback function pointers.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
11 Dynamic bindings to shared C libraries are data-driven by cross-platform binding specification
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
12 using a compact plain text format ; an initial repository of bindings to a couple of
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
13 common C libraries (OpenGL, SDL, Expat, glew, CUDA, OpenCL, ODE, R) comes with the package.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
14 The package includes a variety of technology demos and OS-specific notes for installation of shared libraries.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
15 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
16 \details{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
17 \pkg{rdyncall} offers a stack of interoperability technologies for working
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
18 with foreign compiled languages using cross-platform portable abstraction
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
19 methods.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
20
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
21 For R application development, the package facilitates direct access from R
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
22 to the C Application Programming Interface (API) of common libraries.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
23 This enables a new style of development: R applications can use
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
24 low-level services of portable C libraries.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
25 System-level code can be implemented in R without leaving the language.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
26 C APIs can be explored from within the R interpreter.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
27 Moving the R code from one platform to the other does not involve
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
28 recompilation.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
29 Ofcourse, the run-time libraries need to be installed using a standard
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
30 procedure of the target Operating-System Distribution.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
31 See \link{rdyncall-demos} for details on this.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
32
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
33 For R core development and research, the package provides an improved Foreign
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
34 Function Interface (FFI) that can be used to call arbitrary
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
35 foreign precompiled C code without the need for additional
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
36 compilation of wrapper code. The back-end library is extendable with new
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
37 calling conventions (such as Fortran,Pascal,COM,etc.. - which has not been
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
38 the focus as of this release, but might be supported officially in the near
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
39 futurue).
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
40 Basic type-safety checks for argument passing and framework support for
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
41 working with foreign C data types such as pointers, arrays, structs and
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
42 wrapping of R functions into first-level C callback function pointers
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
43 round up this framework.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
44 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
45 \section{Overview}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
46 \itemize{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
47 \item Flexible FFI with support for almost all C types, type-safety checks and multiple calling conventions. See \code{\link{.dyncall}}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
48 \item Loading of shared libraries with \emph{automatic unload management} and using direct access to OS linker. See \code{\link{.dynload}}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
49 \item Cross-platform naming and loading of shared libraries. See \code{\link{dynfind}}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
50 \item Binding C library functions via thin call wrappers. See \code{\link{dynbind}}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
51 \item Handling of foreign C pointer, array and struct/union data types. See \code{\link{packing}} and \code{\link{struct}}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
52 \item Dynamic wrapping of R functions as C function pointers to be used in C callbacks. See \code{\link{new.callback}}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
53 \item Dynamic bindings to standard and common C libraries and APIs (functions, variables, macro constants, enums, struct and union types). See \code{\link{dynport}}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
54 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
55 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
56 \section{Getting Started}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
57 Several demos ranging from simple FFI calls to the C standard math library up to more complex 3D OpenGL/SDL Applications are available.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
58 See \code{demos(package="rdyncall")} for an overview.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
59 Some demos require shared C libraries to be installed in the system. Please read \link{rdyncall-demos} for details.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
60 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
61 \section{Supported Platforms}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
62 The low-level implementation is mainly based on libraries from the DynCall
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
63 Project (\url{http://dyncall.org}). The library suite is distributed
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
64 as part of the package source tree.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
65
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
66 The dyncall and dyncallback libraries implement generic low-level services
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
67 with the help of a small amount of hand-written assembly code and
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
68 careful modeling of the target machine's calling sequence
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
69 for each platform to support.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
70
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
71 As of version 0.6, the following processor architectures are supported:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
72
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
73 \itemize{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
74 \item Intel i386 32-bit and AMD 64-bit Platforms
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
75 \item ARM 32-bit (OABI, EABI and ARMHF ABI with support for Thumb)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
76 \item PowerPC 32-bit (support for callbacks not implemented for Linux/BSD)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
77 \item MIPS 32- and 64-bit (support for callbacks not yet implemented)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
78 \item SPARC 32- and 64-bit (support for callbacks not yet implemented)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
79 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
80
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
81 The DynCall libraries are tested on Linux, Mac OS X, Windows, BSD derivates
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
82 and more exotic platforms such as game consoles and Plan9.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
83 Please see the details on portability for \link{dyncall}, \link{dyncallback} and \link{dynload}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
84 and the official DynCall manual for full details of the back-end.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
85 The R Package has been tested on several major R platforms.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
86 The following gives a list of comments on platforms about the status of this package.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
87
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
88 \tabular{l}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
89 \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
90 Linux Debian 4/ppc32 , R-2.4.0 : ok, but no callbacks. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
91 Linux Debian 5/arm , R-2.7.0 : ok, SDL not tested. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
92 Linux Debian 6/x86 , R-2.12.2: ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
93 Linux Debian 6/x64 , R-2.12.2: ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
94 Linux Ubuntu 10/armv7, R-2.14 : ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
95 Linux Fedora 14/x86 : ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
96 Linux Ubuntu 12/i386 , R-2.15.1: ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
97 Mac OS X 10.4/ppc , R-2.10.0: ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
98 Mac OS X 10.6/x86 , R-2.12.2: ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
99 Mac OS X 10.6/x64 , R-2.12.2: ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
100 Mac OS X 10.7/x64 , R-2.15.1: ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
101 NetBSD 5.0/x86 : ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
102 NetBSD 5.1/x64 : ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
103 OpenBSD 4.8/x64 , R-2.7.0 : SDL failed. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
104 Windows XP/x86 , R-2.12.2: ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
105 Windows 7/x86 , R-2.12.2: ok. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
106 Windows 7/x64 , R-2.12.2: ok, use correct 64-bit SDL DLL, SDL extension not tested - see \link{rdyncall-demos}) \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
107 FreeBSD 8.2/x86 : build ok, no tests made for X11. \cr
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 \references{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
111 Adler, D. (2012) \dQuote{Foreign Library Interface}, \emph{The R Journal}, \bold{4(1)}, 30--40, June 2012.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
112 \url{http://journal.r-project.org/archive/2012-1/RJournal_2012-1_Adler.pdf}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
113
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
114 Adler, D., Philipp, T. (2008) \emph{DynCall Project}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
115 \url{http://dyncall.org}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
116 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
117 \examples{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
118 \donttest{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
119 # multimedia example
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
120 # load dynports for OpenGL, Simple DirectMedia library
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
121 # globals:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
122 surface <- NULL
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
123 # init SDL and OpenGL
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
124 init <- function()
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
125 {
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
126 dynport(SDL)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
127 dynport(GL)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
128 if ( SDL_Init(SDL_INIT_VIDEO) != 0 ) stop("SDL_Init failed")
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
129 surface <<- SDL_SetVideoMode(320,240,32,SDL_DOUBLEBUF+SDL_OPENGL)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
130 cat("surface dimension:", surface$w, "x",surface$h,sep="")
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
131 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
132 # draw blue screen
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
133 updateSurface <- function(t)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
134 {
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
135 glClearColor(0,0,t \%\% 1,0)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
136 glClear(GL_COLOR_BUFFER_BIT+GL_DEPTH_BUFFER_BIT)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
137 SDL_GL_SwapBuffers()
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
138 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
139 # wait till close
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
140 mainloop <- function()
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
141 {
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
142 quit <- FALSE
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
143 evt <- new.struct(SDL_Event)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
144 base <- SDL_GetTicks() / 1000
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
145 t <- 0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
146 while(!quit) {
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
147 updateSurface(t)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
148 while(SDL_PollEvent(evt)) {
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
149 if ( evt$type == SDL_QUIT ) quit <- TRUE
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
150 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
151 now <- SDL_GetTicks() / 1000
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
152 t <- now - base
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
153 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
154 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
155 init()
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
156 mainloop()
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
157 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
158 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
159 \keyword{programming}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
160 \keyword{interface}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
161