ffi 1.17.0.rc1-aarch64-linux-musl

Sign up to get free protection for your applications and to get access to all the features.
Files changed (134) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +442 -0
  3. data/COPYING +49 -0
  4. data/Gemfile +21 -0
  5. data/LICENSE +24 -0
  6. data/LICENSE.SPECS +22 -0
  7. data/README.md +137 -0
  8. data/Rakefile +206 -0
  9. data/ffi.gemspec +42 -0
  10. data/lib/2.5/ffi_c.so +0 -0
  11. data/lib/2.6/ffi_c.so +0 -0
  12. data/lib/2.7/ffi_c.so +0 -0
  13. data/lib/3.0/ffi_c.so +0 -0
  14. data/lib/3.1/ffi_c.so +0 -0
  15. data/lib/3.2/ffi_c.so +0 -0
  16. data/lib/3.3/ffi_c.so +0 -0
  17. data/lib/ffi/abstract_memory.rb +44 -0
  18. data/lib/ffi/autopointer.rb +188 -0
  19. data/lib/ffi/buffer.rb +4 -0
  20. data/lib/ffi/callback.rb +4 -0
  21. data/lib/ffi/compat.rb +43 -0
  22. data/lib/ffi/data_converter.rb +67 -0
  23. data/lib/ffi/dynamic_library.rb +118 -0
  24. data/lib/ffi/enum.rb +302 -0
  25. data/lib/ffi/errno.rb +43 -0
  26. data/lib/ffi/ffi.rb +50 -0
  27. data/lib/ffi/function.rb +71 -0
  28. data/lib/ffi/io.rb +62 -0
  29. data/lib/ffi/library.rb +576 -0
  30. data/lib/ffi/library_path.rb +109 -0
  31. data/lib/ffi/managedstruct.rb +84 -0
  32. data/lib/ffi/memorypointer.rb +1 -0
  33. data/lib/ffi/platform/aarch64-darwin/types.conf +130 -0
  34. data/lib/ffi/platform/aarch64-freebsd/types.conf +128 -0
  35. data/lib/ffi/platform/aarch64-freebsd12/types.conf +181 -0
  36. data/lib/ffi/platform/aarch64-linux/types.conf +175 -0
  37. data/lib/ffi/platform/aarch64-openbsd/types.conf +134 -0
  38. data/lib/ffi/platform/aarch64-windows/types.conf +52 -0
  39. data/lib/ffi/platform/arm-freebsd/types.conf +152 -0
  40. data/lib/ffi/platform/arm-freebsd12/types.conf +152 -0
  41. data/lib/ffi/platform/arm-linux/types.conf +132 -0
  42. data/lib/ffi/platform/hppa1.1-linux/types.conf +178 -0
  43. data/lib/ffi/platform/hppa2.0-linux/types.conf +178 -0
  44. data/lib/ffi/platform/i386-cygwin/types.conf +3 -0
  45. data/lib/ffi/platform/i386-darwin/types.conf +100 -0
  46. data/lib/ffi/platform/i386-freebsd/types.conf +152 -0
  47. data/lib/ffi/platform/i386-freebsd12/types.conf +152 -0
  48. data/lib/ffi/platform/i386-gnu/types.conf +107 -0
  49. data/lib/ffi/platform/i386-linux/types.conf +103 -0
  50. data/lib/ffi/platform/i386-netbsd/types.conf +126 -0
  51. data/lib/ffi/platform/i386-openbsd/types.conf +128 -0
  52. data/lib/ffi/platform/i386-solaris/types.conf +122 -0
  53. data/lib/ffi/platform/i386-windows/types.conf +52 -0
  54. data/lib/ffi/platform/ia64-linux/types.conf +104 -0
  55. data/lib/ffi/platform/loongarch64-linux/types.conf +141 -0
  56. data/lib/ffi/platform/mips-linux/types.conf +102 -0
  57. data/lib/ffi/platform/mips64-linux/types.conf +104 -0
  58. data/lib/ffi/platform/mips64el-linux/types.conf +104 -0
  59. data/lib/ffi/platform/mipsel-linux/types.conf +102 -0
  60. data/lib/ffi/platform/mipsisa32r6-linux/types.conf +102 -0
  61. data/lib/ffi/platform/mipsisa32r6el-linux/types.conf +102 -0
  62. data/lib/ffi/platform/mipsisa64r6-linux/types.conf +104 -0
  63. data/lib/ffi/platform/mipsisa64r6el-linux/types.conf +104 -0
  64. data/lib/ffi/platform/powerpc-aix/types.conf +180 -0
  65. data/lib/ffi/platform/powerpc-darwin/types.conf +100 -0
  66. data/lib/ffi/platform/powerpc-linux/types.conf +130 -0
  67. data/lib/ffi/platform/powerpc-openbsd/types.conf +156 -0
  68. data/lib/ffi/platform/powerpc64-linux/types.conf +104 -0
  69. data/lib/ffi/platform/powerpc64le-linux/types.conf +100 -0
  70. data/lib/ffi/platform/riscv64-linux/types.conf +104 -0
  71. data/lib/ffi/platform/s390-linux/types.conf +102 -0
  72. data/lib/ffi/platform/s390x-linux/types.conf +102 -0
  73. data/lib/ffi/platform/sparc-linux/types.conf +102 -0
  74. data/lib/ffi/platform/sparc-solaris/types.conf +128 -0
  75. data/lib/ffi/platform/sparcv9-linux/types.conf +102 -0
  76. data/lib/ffi/platform/sparcv9-openbsd/types.conf +156 -0
  77. data/lib/ffi/platform/sparcv9-solaris/types.conf +128 -0
  78. data/lib/ffi/platform/sw_64-linux/types.conf +141 -0
  79. data/lib/ffi/platform/x86_64-cygwin/types.conf +3 -0
  80. data/lib/ffi/platform/x86_64-darwin/types.conf +130 -0
  81. data/lib/ffi/platform/x86_64-dragonflybsd/types.conf +130 -0
  82. data/lib/ffi/platform/x86_64-freebsd/types.conf +128 -0
  83. data/lib/ffi/platform/x86_64-freebsd12/types.conf +158 -0
  84. data/lib/ffi/platform/x86_64-haiku/types.conf +117 -0
  85. data/lib/ffi/platform/x86_64-linux/types.conf +132 -0
  86. data/lib/ffi/platform/x86_64-msys/types.conf +119 -0
  87. data/lib/ffi/platform/x86_64-netbsd/types.conf +128 -0
  88. data/lib/ffi/platform/x86_64-openbsd/types.conf +134 -0
  89. data/lib/ffi/platform/x86_64-solaris/types.conf +122 -0
  90. data/lib/ffi/platform/x86_64-windows/types.conf +52 -0
  91. data/lib/ffi/platform.rb +187 -0
  92. data/lib/ffi/pointer.rb +167 -0
  93. data/lib/ffi/struct.rb +317 -0
  94. data/lib/ffi/struct_by_reference.rb +72 -0
  95. data/lib/ffi/struct_layout.rb +96 -0
  96. data/lib/ffi/struct_layout_builder.rb +227 -0
  97. data/lib/ffi/tools/const_generator.rb +232 -0
  98. data/lib/ffi/tools/generator.rb +105 -0
  99. data/lib/ffi/tools/generator_task.rb +32 -0
  100. data/lib/ffi/tools/struct_generator.rb +195 -0
  101. data/lib/ffi/tools/types_generator.rb +137 -0
  102. data/lib/ffi/types.rb +222 -0
  103. data/lib/ffi/union.rb +43 -0
  104. data/lib/ffi/variadic.rb +80 -0
  105. data/lib/ffi/version.rb +3 -0
  106. data/lib/ffi.rb +27 -0
  107. data/rakelib/ffi_gem_helper.rb +65 -0
  108. data/samples/getlogin.rb +8 -0
  109. data/samples/getpid.rb +8 -0
  110. data/samples/gettimeofday.rb +18 -0
  111. data/samples/hello.rb +8 -0
  112. data/samples/hello_ractor.rb +11 -0
  113. data/samples/inotify.rb +60 -0
  114. data/samples/pty.rb +75 -0
  115. data/samples/qsort.rb +20 -0
  116. data/samples/qsort_ractor.rb +28 -0
  117. data/sig/ffi/abstract_memory.rbs +164 -0
  118. data/sig/ffi/auto_pointer.rbs +27 -0
  119. data/sig/ffi/buffer.rbs +18 -0
  120. data/sig/ffi/data_converter.rbs +10 -0
  121. data/sig/ffi/dynamic_library.rbs +9 -0
  122. data/sig/ffi/enum.rbs +38 -0
  123. data/sig/ffi/function.rbs +39 -0
  124. data/sig/ffi/library.rbs +42 -0
  125. data/sig/ffi/native_type.rbs +86 -0
  126. data/sig/ffi/pointer.rbs +42 -0
  127. data/sig/ffi/struct.rbs +76 -0
  128. data/sig/ffi/struct_by_reference.rbs +11 -0
  129. data/sig/ffi/struct_by_value.rbs +7 -0
  130. data/sig/ffi/struct_layout.rbs +9 -0
  131. data/sig/ffi/struct_layout_builder.rbs +5 -0
  132. data/sig/ffi/type.rbs +39 -0
  133. data/sig/ffi.rbs +26 -0
  134. metadata +244 -0
data/lib/ffi/io.rb ADDED
@@ -0,0 +1,62 @@
1
+ #
2
+ # Copyright (C) 2008, 2009 Wayne Meissner
3
+ #
4
+ # This file is part of ruby-ffi.
5
+ #
6
+ # All rights reserved.
7
+ #
8
+ # Redistribution and use in source and binary forms, with or without
9
+ # modification, are permitted provided that the following conditions are met:
10
+ #
11
+ # * Redistributions of source code must retain the above copyright notice, this
12
+ # list of conditions and the following disclaimer.
13
+ # * Redistributions in binary form must reproduce the above copyright notice
14
+ # this list of conditions and the following disclaimer in the documentation
15
+ # and/or other materials provided with the distribution.
16
+ # * Neither the name of the Ruby FFI project nor the names of its contributors
17
+ # may be used to endorse or promote products derived from this software
18
+ # without specific prior written permission.
19
+ #
20
+ # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
+ # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
+ # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23
+ # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
24
+ # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
+ # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26
+ # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27
+ # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28
+ # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
+ # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.#
30
+
31
+ module FFI
32
+
33
+ # This module implements a couple of class methods to play with IO.
34
+ module IO
35
+ # @param [Integer] fd file decriptor
36
+ # @param [String] mode mode string
37
+ # @return [::IO]
38
+ # Synonym for IO::for_fd.
39
+ def self.for_fd(fd, mode = "r")
40
+ ::IO.for_fd(fd, mode)
41
+ end
42
+
43
+ # @param [#read] io io to read from
44
+ # @param [AbstractMemory] buf destination for data read from +io+
45
+ # @param [nil, Integer] len maximul number of bytes to read from +io+. If +nil+,
46
+ # read until end of file.
47
+ # @return [Integer] length really read, in bytes
48
+ #
49
+ # A version of IO#read that reads data from an IO and put then into a native buffer.
50
+ #
51
+ # This will be optimized at some future time to eliminate the double copy.
52
+ #
53
+ def self.native_read(io, buf, len)
54
+ tmp = io.read(len)
55
+ return -1 unless tmp
56
+ buf.put_bytes(0, tmp)
57
+ tmp.length
58
+ end
59
+
60
+ end
61
+ end
62
+
@@ -0,0 +1,576 @@
1
+ #
2
+ # Copyright (C) 2008-2010 Wayne Meissner
3
+ #
4
+ # This file is part of ruby-ffi.
5
+ #
6
+ # All rights reserved.
7
+ #
8
+ # Redistribution and use in source and binary forms, with or without
9
+ # modification, are permitted provided that the following conditions are met:
10
+ #
11
+ # * Redistributions of source code must retain the above copyright notice, this
12
+ # list of conditions and the following disclaimer.
13
+ # * Redistributions in binary form must reproduce the above copyright notice
14
+ # this list of conditions and the following disclaimer in the documentation
15
+ # and/or other materials provided with the distribution.
16
+ # * Neither the name of the Ruby FFI project nor the names of its contributors
17
+ # may be used to endorse or promote products derived from this software
18
+ # without specific prior written permission.
19
+ #
20
+ # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
+ # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
+ # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23
+ # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
24
+ # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
+ # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26
+ # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27
+ # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28
+ # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
+ # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.#
30
+
31
+ require 'ffi/dynamic_library'
32
+
33
+ module FFI
34
+ CURRENT_PROCESS = USE_THIS_PROCESS_AS_LIBRARY = FFI.make_shareable(Object.new)
35
+
36
+ # @param [String, FFI::LibraryPath] lib library name or LibraryPath object
37
+ # @return [String] library name formatted for current platform
38
+ # Transform a generic library name to a platform library name
39
+ # @example
40
+ # # Linux
41
+ # FFI.map_library_name 'c' # -> "libc.so.6"
42
+ # FFI.map_library_name 'jpeg' # -> "libjpeg.so"
43
+ # # Windows
44
+ # FFI.map_library_name 'c' # -> "msvcrt.dll"
45
+ # FFI.map_library_name 'jpeg' # -> "jpeg.dll"
46
+ def self.map_library_name(lib)
47
+ # Mangle the library name to reflect the native library naming conventions
48
+ LibraryPath.wrap(lib).to_s
49
+ end
50
+
51
+ # Exception raised when a function is not found in libraries
52
+ class NotFoundError < LoadError
53
+ def initialize(function, *libraries)
54
+ super("Function '#{function}' not found in [#{libraries[0].nil? ? 'current process' : libraries.join(", ")}]")
55
+ end
56
+ end
57
+
58
+ # This module is the base to use native functions.
59
+ #
60
+ # A basic usage may be:
61
+ # require 'ffi'
62
+ #
63
+ # module Hello
64
+ # extend FFI::Library
65
+ # ffi_lib FFI::Library::LIBC
66
+ # attach_function 'puts', [ :string ], :int
67
+ # end
68
+ #
69
+ # Hello.puts("Hello, World")
70
+ #
71
+ #
72
+ module Library
73
+ CURRENT_PROCESS = FFI::CURRENT_PROCESS
74
+ LIBC = FFI::Platform::LIBC
75
+
76
+ # @param mod extended object
77
+ # @return [nil]
78
+ # @raise {RuntimeError} if +mod+ is not a Module
79
+ # Test if extended object is a Module. If not, raise RuntimeError.
80
+ def self.extended(mod)
81
+ raise RuntimeError.new("must only be extended by module") unless mod.kind_of?(::Module)
82
+ end
83
+
84
+
85
+ # @param [Array] names names of libraries to load
86
+ # @return [Array<DynamicLibrary>]
87
+ # @raise {LoadError} if a library cannot be opened
88
+ # Load native libraries.
89
+ def ffi_lib(*names)
90
+ raise LoadError.new("library names list must not be empty") if names.empty?
91
+
92
+ lib_flags = defined?(@ffi_lib_flags) && @ffi_lib_flags
93
+
94
+ @ffi_libs = names.map do |name|
95
+ FFI::DynamicLibrary.send(:load_library, name, lib_flags)
96
+ end
97
+ end
98
+
99
+ # Set the calling convention for {#attach_function} and {#callback}
100
+ #
101
+ # @see http://en.wikipedia.org/wiki/Stdcall#stdcall
102
+ # @note +:stdcall+ is typically used for attaching Windows API functions
103
+ #
104
+ # @param [Symbol] convention one of +:default+, +:stdcall+
105
+ # @return [Symbol] the new calling convention
106
+ def ffi_convention(convention = nil)
107
+ @ffi_convention ||= :default
108
+ @ffi_convention = convention if convention
109
+ @ffi_convention
110
+ end
111
+
112
+ # @see #ffi_lib
113
+ # @return [Array<FFI::DynamicLibrary>] array of currently loaded FFI libraries
114
+ # @raise [LoadError] if no libraries have been loaded (using {#ffi_lib})
115
+ # Get FFI libraries loaded using {#ffi_lib}.
116
+ def ffi_libraries
117
+ raise LoadError.new("no library specified") if !defined?(@ffi_libs) || @ffi_libs.empty?
118
+ @ffi_libs
119
+ end
120
+
121
+ # Flags used in {#ffi_lib}.
122
+ #
123
+ # This map allows you to supply symbols to {#ffi_lib_flags} instead of
124
+ # the actual constants.
125
+ FlagsMap = {
126
+ :global => DynamicLibrary::RTLD_GLOBAL,
127
+ :local => DynamicLibrary::RTLD_LOCAL,
128
+ :lazy => DynamicLibrary::RTLD_LAZY,
129
+ :now => DynamicLibrary::RTLD_NOW
130
+ }
131
+
132
+ # Sets library flags for {#ffi_lib}.
133
+ #
134
+ # @example
135
+ # ffi_lib_flags(:lazy, :local) # => 5
136
+ #
137
+ # @param [Symbol, …] flags (see {FlagsMap})
138
+ # @return [Integer] the new value
139
+ def ffi_lib_flags(*flags)
140
+ @ffi_lib_flags = flags.inject(0) { |result, f| result | FlagsMap[f] }
141
+ end
142
+
143
+
144
+ ##
145
+ # @overload attach_function(func, args, returns, options = {})
146
+ # @example attach function without an explicit name
147
+ # module Foo
148
+ # extend FFI::Library
149
+ # ffi_lib FFI::Library::LIBC
150
+ # attach_function :malloc, [:size_t], :pointer
151
+ # end
152
+ # # now callable via Foo.malloc
153
+ # @overload attach_function(name, func, args, returns, options = {})
154
+ # @example attach function with an explicit name
155
+ # module Bar
156
+ # extend FFI::Library
157
+ # ffi_lib FFI::Library::LIBC
158
+ # attach_function :c_malloc, :malloc, [:size_t], :pointer
159
+ # end
160
+ # # now callable via Bar.c_malloc
161
+ #
162
+ # Attach C function +func+ to this module.
163
+ #
164
+ #
165
+ # @param [#to_s] name name of ruby method to attach as
166
+ # @param [#to_s] func name of C function to attach
167
+ # @param [Array<Symbol>] args an array of types
168
+ # @param [Symbol] returns type of return value
169
+ # @option options [Boolean] :blocking (@blocking) set to true if the C function is a blocking call
170
+ # @option options [Symbol] :convention (:default) calling convention (see {#ffi_convention})
171
+ # @option options [FFI::Enums] :enums
172
+ # @option options [Hash] :type_map
173
+ #
174
+ # @return [FFI::VariadicInvoker]
175
+ #
176
+ # @raise [FFI::NotFoundError] if +func+ cannot be found in the attached libraries (see {#ffi_lib})
177
+ def attach_function(name, func, args, returns = nil, options = nil)
178
+ mname, a2, a3, a4, a5 = name, func, args, returns, options
179
+ cname, arg_types, ret_type, opts = (a4 && (a2.is_a?(String) || a2.is_a?(Symbol))) ? [ a2, a3, a4, a5 ] : [ mname.to_s, a2, a3, a4 ]
180
+
181
+ # Convert :foo to the native type
182
+ arg_types = arg_types.map { |e| find_type(e) }
183
+ options = {
184
+ :convention => ffi_convention,
185
+ :type_map => defined?(@ffi_typedefs) ? @ffi_typedefs : nil,
186
+ :blocking => defined?(@blocking) && @blocking,
187
+ :enums => defined?(@ffi_enums) ? @ffi_enums : nil,
188
+ }
189
+
190
+ @blocking = false
191
+ options.merge!(opts) if opts && opts.is_a?(Hash)
192
+
193
+ # Try to locate the function in any of the libraries
194
+ invokers = []
195
+ ffi_libraries.each do |lib|
196
+ if invokers.empty?
197
+ begin
198
+ function = nil
199
+ function_names(cname, arg_types).find do |fname|
200
+ function = lib.find_function(fname)
201
+ end
202
+ raise LoadError unless function
203
+
204
+ invokers << if arg_types[-1] == FFI::NativeType::VARARGS
205
+ VariadicInvoker.new(function, arg_types, find_type(ret_type), options)
206
+
207
+ else
208
+ Function.new(find_type(ret_type), arg_types, function, options)
209
+ end
210
+
211
+ rescue LoadError
212
+ end
213
+ end
214
+ end
215
+ invoker = invokers.compact.shift
216
+ raise FFI::NotFoundError.new(cname.to_s, ffi_libraries.map { |lib| lib.name }) unless invoker
217
+
218
+ invoker.attach(self, mname.to_s)
219
+ invoker
220
+ end
221
+
222
+ # @param [#to_s] name function name
223
+ # @param [Array] arg_types function's argument types
224
+ # @return [Array<String>]
225
+ # This function returns a list of possible names to lookup.
226
+ # @note Function names on windows may be decorated if they are using stdcall. See
227
+ # * http://en.wikipedia.org/wiki/Name_mangling#C_name_decoration_in_Microsoft_Windows
228
+ # * http://msdn.microsoft.com/en-us/library/zxk0tw93%28v=VS.100%29.aspx
229
+ # * http://en.wikibooks.org/wiki/X86_Disassembly/Calling_Conventions#STDCALL
230
+ # Note that decorated names can be overridden via def files. Also note that the
231
+ # windows api, although using, doesn't have decorated names.
232
+ def function_names(name, arg_types)
233
+ result = [name.to_s]
234
+ if ffi_convention == :stdcall
235
+ # Get the size of each parameter
236
+ size = arg_types.inject(0) do |mem, arg|
237
+ size = arg.size
238
+ # The size must be a multiple of 4
239
+ size += (4 - size) % 4
240
+ mem + size
241
+ end
242
+
243
+ result << "_#{name.to_s}@#{size}" # win32
244
+ result << "#{name.to_s}@#{size}" # win64
245
+ end
246
+ result
247
+ end
248
+
249
+ # @overload attach_variable(mname, cname, type)
250
+ # @param [#to_s] mname name of ruby method to attach as
251
+ # @param [#to_s] cname name of C variable to attach
252
+ # @param [DataConverter, Struct, Symbol, Type] type C variable's type
253
+ # @example
254
+ # module Bar
255
+ # extend FFI::Library
256
+ # ffi_lib 'my_lib'
257
+ # attach_variable :c_myvar, :myvar, :long
258
+ # end
259
+ # # now callable via Bar.c_myvar
260
+ # @overload attach_variable(cname, type)
261
+ # @param [#to_s] mname name of ruby method to attach as
262
+ # @param [DataConverter, Struct, Symbol, Type] type C variable's type
263
+ # @example
264
+ # module Bar
265
+ # extend FFI::Library
266
+ # ffi_lib 'my_lib'
267
+ # attach_variable :myvar, :long
268
+ # end
269
+ # # now callable via Bar.myvar
270
+ # @return [DynamicLibrary::Symbol]
271
+ # @raise {FFI::NotFoundError} if +cname+ cannot be found in libraries
272
+ #
273
+ # Attach C variable +cname+ to this module.
274
+ def attach_variable(mname, a1, a2 = nil)
275
+ cname, type = a2 ? [ a1, a2 ] : [ mname.to_s, a1 ]
276
+ mname = mname.to_sym
277
+ address = nil
278
+ ffi_libraries.each do |lib|
279
+ begin
280
+ address = lib.find_variable(cname.to_s)
281
+ break unless address.nil?
282
+ rescue LoadError
283
+ end
284
+ end
285
+
286
+ raise FFI::NotFoundError.new(cname, ffi_libraries) if address.nil? || address.null?
287
+ if type.is_a?(Class) && type < FFI::Struct
288
+ # If it is a global struct, just attach directly to the pointer
289
+ s = s = type.new(address) # Assigning twice to suppress unused variable warning
290
+ self.module_eval <<-code, __FILE__, __LINE__
291
+ @ffi_gsvars = {} unless defined?(@ffi_gsvars)
292
+ @ffi_gsvars[#{mname.inspect}] = s
293
+ def self.#{mname}
294
+ @ffi_gsvars[#{mname.inspect}]
295
+ end
296
+ code
297
+
298
+ else
299
+ sc = Class.new(FFI::Struct)
300
+ sc.layout :gvar, find_type(type)
301
+ s = sc.new(address)
302
+ #
303
+ # Attach to this module as mname/mname=
304
+ #
305
+ self.module_eval <<-code, __FILE__, __LINE__
306
+ @ffi_gvars = {} unless defined?(@ffi_gvars)
307
+ @ffi_gvars[#{mname.inspect}] = s
308
+ def self.#{mname}
309
+ @ffi_gvars[#{mname.inspect}][:gvar]
310
+ end
311
+ def self.#{mname}=(value)
312
+ @ffi_gvars[#{mname.inspect}][:gvar] = value
313
+ end
314
+ code
315
+
316
+ end
317
+
318
+ address
319
+ end
320
+
321
+
322
+ # @overload callback(name, params, ret)
323
+ # @param name callback name to add to type map
324
+ # @param [Array] params array of parameters' types
325
+ # @param [DataConverter, Struct, Symbol, Type] ret callback return type
326
+ # @overload callback(params, ret)
327
+ # @param [Array] params array of parameters' types
328
+ # @param [DataConverter, Struct, Symbol, Type] ret callback return type
329
+ # @return [FFI::CallbackInfo]
330
+ def callback(*args)
331
+ raise ArgumentError, "wrong number of arguments" if args.length < 2 || args.length > 3
332
+ name, params, ret = if args.length == 3
333
+ args
334
+ else
335
+ [ nil, args[0], args[1] ]
336
+ end
337
+
338
+ native_params = params.map { |e| find_type(e) }
339
+ raise ArgumentError, "callbacks cannot have variadic parameters" if native_params.include?(FFI::Type::VARARGS)
340
+ options = Hash.new
341
+ options[:convention] = ffi_convention
342
+ options[:enums] = @ffi_enums if defined?(@ffi_enums)
343
+ ret_type = find_type(ret)
344
+ if ret_type == Type::STRING
345
+ raise TypeError, ":string is not allowed as return type of callbacks"
346
+ end
347
+ cb = FFI::CallbackInfo.new(ret_type, native_params, options)
348
+
349
+ # Add to the symbol -> type map (unless there was no name)
350
+ unless name.nil?
351
+ typedef cb, name
352
+ end
353
+
354
+ cb
355
+ end
356
+
357
+ # Register or get an already registered type definition.
358
+ #
359
+ # To register a new type definition, +old+ should be a {FFI::Type}. +add+
360
+ # is in this case the type definition.
361
+ #
362
+ # If +old+ is a {DataConverter}, a {Type::Mapped} is returned.
363
+ #
364
+ # If +old+ is +:enum+
365
+ # * and +add+ is an +Array+, a call to {#enum} is made with +add+ as single parameter;
366
+ # * in others cases, +info+ is used to create a named enum.
367
+ #
368
+ # If +old+ is a key for type map, #typedef get +old+ type definition.
369
+ #
370
+ # @param [DataConverter, Symbol, Type] old
371
+ # @param [Symbol] add
372
+ # @param [Symbol] info
373
+ # @return [FFI::Enum, FFI::Type]
374
+ def typedef(old, add, info=nil)
375
+ @ffi_typedefs = Hash.new unless defined?(@ffi_typedefs)
376
+
377
+ @ffi_typedefs[add] = if old.kind_of?(FFI::Type)
378
+ old
379
+
380
+ elsif @ffi_typedefs.has_key?(old)
381
+ @ffi_typedefs[old]
382
+
383
+ elsif old.is_a?(DataConverter)
384
+ FFI::Type::Mapped.new(old)
385
+
386
+ elsif old == :enum
387
+ if add.kind_of?(Array)
388
+ self.enum(add)
389
+ else
390
+ self.enum(info, add)
391
+ end
392
+
393
+ else
394
+ FFI.find_type(old)
395
+ end
396
+ end
397
+
398
+ # @param [DataConverter, Type, Struct, Symbol] t type to find
399
+ # @return [Type]
400
+ # Find a type definition.
401
+ def find_type(t)
402
+ if t.kind_of?(Type)
403
+ t
404
+
405
+ elsif defined?(@ffi_typedefs) && @ffi_typedefs.has_key?(t)
406
+ @ffi_typedefs[t]
407
+
408
+ elsif t.is_a?(Class) && t < Struct
409
+ Type::POINTER
410
+
411
+ elsif t.is_a?(DataConverter)
412
+ # Add a typedef so next time the converter is used, it hits the cache
413
+ typedef Type::Mapped.new(t), t
414
+
415
+ end || FFI.find_type(t)
416
+ end
417
+
418
+ private
419
+ # Generic enum builder
420
+ # @param [Class] klass can be one of FFI::Enum or FFI::Bitmask
421
+ # @param args (see #enum or #bitmask)
422
+ def generic_enum(klass, *args)
423
+ native_type = args.first.kind_of?(FFI::Type) ? args.shift : nil
424
+ name, values = if args[0].kind_of?(Symbol) && args[1].kind_of?(Array)
425
+ [ args[0], args[1] ]
426
+ elsif args[0].kind_of?(Array)
427
+ [ nil, args[0] ]
428
+ else
429
+ [ nil, args ]
430
+ end
431
+ @ffi_enums = FFI::Enums.new unless defined?(@ffi_enums)
432
+ @ffi_enums << (e = native_type ? klass.new(native_type, values, name) : klass.new(values, name))
433
+
434
+ # If called with a name, add a typedef alias
435
+ typedef(e, name) if name
436
+ e
437
+ end
438
+
439
+ public
440
+ # @overload enum(name, values)
441
+ # Create a named enum.
442
+ # @example
443
+ # enum :foo, [:zero, :one, :two] # named enum
444
+ # @param [Symbol] name name for new enum
445
+ # @param [Array] values values for enum
446
+ # @overload enum(*args)
447
+ # Create an unnamed enum.
448
+ # @example
449
+ # enum :zero, :one, :two # unnamed enum
450
+ # @param args values for enum
451
+ # @overload enum(values)
452
+ # Create an unnamed enum.
453
+ # @example
454
+ # enum [:zero, :one, :two] # unnamed enum, equivalent to above example
455
+ # @param [Array] values values for enum
456
+ # @overload enum(native_type, name, values)
457
+ # Create a named enum and specify the native type.
458
+ # @example
459
+ # enum FFI::Type::UINT64, :foo, [:zero, :one, :two] # named enum
460
+ # @param [FFI::Type] native_type native type for new enum
461
+ # @param [Symbol] name name for new enum
462
+ # @param [Array] values values for enum
463
+ # @overload enum(native_type, *args)
464
+ # Create an unnamed enum and specify the native type.
465
+ # @example
466
+ # enum FFI::Type::UINT64, :zero, :one, :two # unnamed enum
467
+ # @param [FFI::Type] native_type native type for new enum
468
+ # @param args values for enum
469
+ # @overload enum(native_type, values)
470
+ # Create an unnamed enum and specify the native type.
471
+ # @example
472
+ # enum Type::UINT64, [:zero, :one, :two] # unnamed enum, equivalent to above example
473
+ # @param [FFI::Type] native_type native type for new enum
474
+ # @param [Array] values values for enum
475
+ # @return [FFI::Enum]
476
+ # Create a new {FFI::Enum}.
477
+ def enum(*args)
478
+ generic_enum(FFI::Enum, *args)
479
+ end
480
+
481
+ # @overload bitmask(name, values)
482
+ # Create a named bitmask
483
+ # @example
484
+ # bitmask :foo, [:red, :green, :blue] # bits 0,1,2 are used
485
+ # bitmask :foo, [:red, :green, 5, :blue] # bits 0,5,6 are used
486
+ # @param [Symbol] name for new bitmask
487
+ # @param [Array<Symbol, Integer>] values for new bitmask
488
+ # @overload bitmask(*args)
489
+ # Create an unamed bitmask
490
+ # @example
491
+ # bm = bitmask :red, :green, :blue # bits 0,1,2 are used
492
+ # bm = bitmask :red, :green, 5, blue # bits 0,5,6 are used
493
+ # @param [Symbol, Integer] args values for new bitmask
494
+ # @overload bitmask(values)
495
+ # Create an unamed bitmask
496
+ # @example
497
+ # bm = bitmask [:red, :green, :blue] # bits 0,1,2 are used
498
+ # bm = bitmask [:red, :green, 5, blue] # bits 0,5,6 are used
499
+ # @param [Array<Symbol, Integer>] values for new bitmask
500
+ # @overload bitmask(native_type, name, values)
501
+ # Create a named enum and specify the native type.
502
+ # @example
503
+ # bitmask FFI::Type::UINT64, :foo, [:red, :green, :blue]
504
+ # @param [FFI::Type] native_type native type for new bitmask
505
+ # @param [Symbol] name for new bitmask
506
+ # @param [Array<Symbol, Integer>] values for new bitmask
507
+ # @overload bitmask(native_type, *args)
508
+ # @example
509
+ # bitmask FFI::Type::UINT64, :red, :green, :blue
510
+ # @param [FFI::Type] native_type native type for new bitmask
511
+ # @param [Symbol, Integer] args values for new bitmask
512
+ # @overload bitmask(native_type, values)
513
+ # Create a named enum and specify the native type.
514
+ # @example
515
+ # bitmask FFI::Type::UINT64, [:red, :green, :blue]
516
+ # @param [FFI::Type] native_type native type for new bitmask
517
+ # @param [Array<Symbol, Integer>] values for new bitmask
518
+ # @return [FFI::Bitmask]
519
+ # Create a new FFI::Bitmask
520
+ def bitmask(*args)
521
+ generic_enum(FFI::Bitmask, *args)
522
+ end
523
+
524
+ # @param name
525
+ # @return [FFI::Enum]
526
+ # Find an enum by name.
527
+ def enum_type(name)
528
+ @ffi_enums.find(name) if defined?(@ffi_enums)
529
+ end
530
+
531
+ # @param symbol
532
+ # @return [FFI::Enum]
533
+ # Find an enum by a symbol it contains.
534
+ def enum_value(symbol)
535
+ @ffi_enums.__map_symbol(symbol)
536
+ end
537
+
538
+ # Retrieve all attached functions and their function signature
539
+ #
540
+ # This method returns a Hash of method names of attached functions connected by #attach_function and the corresponding function type.
541
+ # The function type responds to #return_type and #param_types which return the FFI types of the function signature.
542
+ #
543
+ # @return [Hash< Symbol => [FFI::Function, FFI::VariadicInvoker] >]
544
+ def attached_functions
545
+ @ffi_functions || {}
546
+ end
547
+
548
+ # Retrieve all attached variables and their type
549
+ #
550
+ # This method returns a Hash of variable names and the corresponding type or variables connected by #attach_variable .
551
+ #
552
+ # @return [Hash< Symbol => ffi_type >]
553
+ def attached_variables
554
+ (
555
+ (defined?(@ffi_gsvars) ? @ffi_gsvars : {}).map do |name, gvar|
556
+ [name, gvar.class]
557
+ end +
558
+ (defined?(@ffi_gvars) ? @ffi_gvars : {}).map do |name, gvar|
559
+ [name, gvar.layout[:gvar].type]
560
+ end
561
+ ).to_h
562
+ end
563
+
564
+ # Freeze all definitions of the module
565
+ #
566
+ # This freezes the module's definitions, so that it can be used in a Ractor.
567
+ # No further methods or variables can be attached and no further enums or typedefs can be created in this module afterwards.
568
+ def freeze
569
+ instance_variables.each do |name|
570
+ var = instance_variable_get(name)
571
+ FFI.make_shareable(var)
572
+ end
573
+ nil
574
+ end
575
+ end
576
+ end