ffi-libfuse 0.0.1.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c870a0015b02637bb7423453df5f208dc2a9b263ac5d68ae9de7a71c7767e005
+  data.tar.gz: 6ea5d671235ce094dbcbaf1e2257cc8879a102af74fc9a5ebc0cf2238e17a6fd
+SHA512:
+  metadata.gz: d80e0f44e8bf7bbb23705c9937c142105aed1eb89bd8cad0f8eba5a8e36b6f590afb35080790df7564f0c2f2f3aec86ef3c99a83a24d8ec3201ca13963ca0e63
+  data.tar.gz: 9937c251e92940a61e0e6d01c9b45ce525a2e0045d6cdcc182d377926d8c671ae3e9de07d128e8344a566ff8cc71d06095514e3701d31065faec57e88e9f383e

data/.yardopts

@@ -0,0 +1 @@
+--markup=markdown

data/README.md

@@ -0,0 +1,100 @@
+# FFI::Libfuse
+
+Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
+
+## Writing a FUSE Filesystem
+
+Create a class that implements the abstract methods of {FFI::Libfuse::Main} and {FFI::Libfuse::FuseOperations}
+
+Call {FFI::Libfuse.fuse_main} to start the filesystem
+
+```ruby
+require 'ffi/libfuse'
+
+class MyFS
+  # include helpers to abstract away from the native C callbacks to more idiomatic Ruby
+  include FFI::Libfuse::Adapter::Ruby
+  
+  # ... FUSE callbacks .... quacks like a FFI:Libfuse::FuseOperations
+  def getattr(*args)
+    #...  
+  end
+  
+  def readdir(*args)
+    #...
+  end
+  
+end
+
+FFI::Libfuse::fuse_main(operations: MyFS.new) if __FILE__ == $0
+```
+
+# Fuse2/Fuse3 compatibility
+
+FFI::Libfuse will prefer Fuse3 over Fuse2 by default. See {FFI::Libfuse::LIBFUSE}
+
+For writing filesystems with backwards/forwards compatibility between fuse version see
+{FFI::Libfuse::Adapter::Fuse2Compat} and {FFI::Libfuse::Adapter::Fuse3Support}
+
+## MACFuse
+
+[macFUSE](https://osxfuse.github.io/) (previously OSXFuse) supports a superset of the Fuse2 api so FFI::Libfuse is
+ intended to work in that environment.
+
+# Multi-threading
+
+Most Ruby filesystems are unlikely to benefit from multi-threaded operation so
+{FFI::Libfuse.fuse_main} as shown above injects the '-s' (single-thread) option by default.
+
+Pass the original options in directly if multi-threaded operation is desired for your filesystem
+
+```ruby
+FFI::Libfuse::fuse_main($0,*ARGV, operations: MyFS.new) if __FILE__ == $0
+```
+
+The {FFI::Libfuse::ThreadPool} can be configured with `-o max_threads=<n>,max_idle_threads=<n>` options
+
+Callbacks that are about to block (and release the GVL for MRI) should call {FFI::Libfuse::ThreadPool.busy}.
+
+A typical scenario would be a filesystem where some callbacks are blocking on network IO.
+
+```ruby
+def read(*args)
+ # prep, validate args etc.. (MRI holding the GVL anyway)
+ FFI::Libfuse::ThreadPool.busy
+ # Now make some REST or other network call to read the data
+end
+```
+
+**Note** Fuse itself has conditions under which filesystem callbacks will be serialized. In particular see
+[this discussion](http://fuse.996288.n3.nabble.com/GetAttr-calls-being-serialised-td11741.html)
+on the serialisation of `#getattr` and `#readdir` calls.
+
+## Under the hood
+
+FFI::Libfuse tries to provide raw access to the underlying libfuse but there some constraints imposed by Ruby.
+
+The functions fuse_main(), fuse_daemonize() and fuse_loop<_mt>() are re-implemented in Ruby so we can provide
+
+ * dynamic compatibility between Fuse2 and Fuse3
+ * integrated support for multi-threading under MRI (see {FFI::Libfuse::ThreadPool})
+ * signal handling in ruby filesystem (eg HUP to reload)
+
+Sending `-o native' will used the native C functions but this exists to assist with testing that FFI::Libfuse has
+similar behaviour to libfuse itself.
+
+See {FFI::Libfuse::Main} and {FFI::Libfuse::FuseCommon}
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/lwoggardner/ffi-libfuse. 
+
+### TODO
+  * Include a MetaFS, PathMapperFS etc (possibly a separate library)
+  * Build a filesystem that can make use of multi-threaded operations
+  * Test with macFUSE
+
+## License
+
+The gem is available under the terms of the [MIT](https://opensource.org/licenses/MIT) License.
+

data/lib/ffi/accessors.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+module FFI
+  # Syntax sugar for FFI::Struct
+  module Accessors
+    # DSL methods for defining struct member accessors
+    module ClassMethods
+      # Define both a reader and a writer for members
+      # @param [Array<Symbol>] attrs the attribute names
+      # @param [String] format
+      #   A format string containing a single %s to convert attr symbol to struct member
+      # @return [void]
+      def ffi_attr_accessor(*attrs, format: '%s')
+        ffi_attr_reader(*attrs, format: format)
+        ffi_attr_writer(*attrs, format: format)
+      end
+
+      #
+      # Define a struct attribute reader for members
+      # @param [Array<Symbol>] attrs the attribute names
+      # @param [String] format
+      #   A format string containing a single %s to convert attr symbol to struct member
+      # @param [Boolean] simple
+      #   Controls how writer methods are defined using block
+      # @param [Proc] block
+      #   An optional block to the struct field(s) into something more useful
+      #
+      #   If simple is true then block takes the struct field value, otherwise method is defined directly from the block
+      #   and should use __method__ to get the attr name, and self.class.ffi_attr_readers[__method__] to get the member
+      #   name
+      # @return [void]
+      def ffi_attr_reader(*attrs, format: '%s', simple: true, &block)
+        attrs.each do |attr|
+          member = (format % attr).to_sym
+          ffi_attr_readers[attr] = member
+          if !block
+            define_method(attr) { self[member] }
+          elsif simple
+            define_method(attr) { block.call(self[member]) }
+          else
+            define_method(attr, &block)
+          end
+        end
+      end
+
+      # Define a struct attribute writer
+      # @param [Array<Symbol>] attrs the attribute names
+      # @param [String] format
+      #   A format string containing a single %s to convert attr symbol to struct member
+      # @param [Boolean] simple
+      #   Controls how writer methods are defined using block
+      # @param [Proc] block
+      #   An optional block to set the input value into the struct field.
+      #
+      #   If simple is true then the struct field is set to the result of calling block with the input value,
+      #   otherwise the method is defined directly from the block. Use __method__[0..-2] to get the attribute name
+      #   and self.class.ffi_attr_writers[__method__[0..-2]] to get the struct field name
+      # @return [void]
+      def ffi_attr_writer(*attrs, format: '%s', simple: true, &block)
+        attrs.each do |attr|
+          member = (format % attr).to_sym
+          ffi_attr_writers[attr.to_sym] = member
+          if !block
+            define_method("#{attr}=") { |val| self[member] = val }
+          elsif simple
+            define_method("#{attr}=") { |val| self[member] = block.call(val) }
+          else
+            define_method("#{attr}=", &block)
+          end
+        end
+      end
+
+      # All defined readers
+      # @return [Hash<Symbol,Symbol>] map of attr names to member names for which readers exist
+      def ffi_attr_readers
+        @ffi_attr_readers ||= {}
+      end
+
+      # All defined writers
+      # @return [Hash<Symbol,Symbol>] map of attr names to member names for which writers exist
+      def ffi_attr_writers
+        @ffi_attr_writers ||= {}
+      end
+
+      # Define individual flag accessors over a bitmask field
+      def ffi_bitflag_accessor(attr, *flags)
+        ffi_bitflag_reader(attr, *flags)
+        ffi_bitflag_writer(attr, *flags)
+      end
+
+      # Define individual flag readers over a bitmask field
+      # @param [Symbol] attr the bitmask member
+      # @param [Array<Symbol>] flags list of flags
+      # @return [void]
+      def ffi_bitflag_reader(attr, *flags)
+        flags.each { |f| ffi_attr_reader(f, simple: false) { self[attr].include?(f) } }
+      end
+
+      # Define individual flag writers over a bitmask field
+      # @param [Symbol] attr the bitmask member
+      # @param [Array<Symbol>] flags list of flags
+      # @return [void]
+      def ffi_bitflag_writer(attr, *flags)
+        flags.each do |f|
+          ffi_attr_writer(f, simple: false) do |v|
+            v ? self[attr] += [f] : self[attr] -= [f]
+            v
+          end
+        end
+      end
+    end
+
+    def self.included(mod)
+      mod.extend(ClassMethods)
+    end
+
+    # Fill the native struct from another object or list of properties
+    # @param [Object] from
+    #    for each attribute we call self.attr=(from.attr)
+    # @param [Hash<Symbol,Object>] args
+    #   for each entry <attr,val> we call self.attr=(val)
+    # @return [self]
+    def fill(from = nil, **args)
+      if from.is_a?(Hash)
+        args.merge!(from)
+      else
+        self.class.ffi_attr_writers.each_key { |v| send("#{v}=", from.send(v)) if from.respond_to?(v) }
+      end
+      args.each_pair { |k, v| send("#{k}=", v) }
+      self
+    end
+
+    def inspect
+      "#{self.class.name} {#{self.class.ffi_attr_readers.keys.map { |r| "#{r}: #{send(r)} " }.join(',')}"
+    end
+
+    # Convert struct to hash
+    # @return [Hash<Symbol,Object>] map of reader attribute name to value
+    def to_h
+      self.class.ffi_attr_readers.keys.each_with_object({}) { |r, h| h[r] = send(r) }
+    end
+  end
+end

data/lib/ffi/devt.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+module FFI
+  # Calculate major/minor device numbers for use with mknod etc..
+  # @see makedev(3)
+  module Device
+    extend FFI::Library
+    ffi_lib FFI::Library::LIBC
+
+    prefix = FFI::Platform::IS_GNU ? 'gnu_dev_' : ''
+
+    # @!method makedev(major,minor)
+    #  @param [Integer] major
+    #  @param [Integer] minor
+    #  @return [Integer] combined major/minor to a single value to pass to mknod etc
+    attach_function :makedev, "#{prefix}makedev".to_sym, %i[int int], :int
+
+    # @!method major(dev)
+    #  @param [Integer] dev
+    #  @return [Integer] the major component of dev
+    attach_function :major, "#{prefix}major".to_sym, [:int], :int
+
+    # @!method minor(dev)
+    #  @param [Integer] dev
+    #  @return [Integer] the minor component of dev
+    attach_function :minor, "#{prefix}minor".to_sym, [:int], :int
+  end
+end

data/lib/ffi/flock.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative 'accessors'
+
+module FFI
+  # Flocking operation
+  class Flock < Struct
+    # Enum definitions associated with Flock
+    module Enums
+      extend FFI::Library
+      seek_whence = %i[seek_set seek_cur seek_end seek_data seek_hole]
+      SeekWhenceShort = enum :short, seek_whence
+      SeekWhence = enum :int, seek_whence
+
+      LockType = enum :short, %i[f_rdlck f_wrlck f_unlck]
+      LockCmd = enum :int, [:f_getlk, 5, :f_setlk, 6, :f_setlkw, 7]
+    end
+
+    include(Accessors)
+
+    layout(type: Enums::LockType, whence: Enums::SeekWhenceShort, start: :off_t, len: :off_t, pid: :pid_t)
+
+    ffi_attr_reader :type, :whence, :start, :len, :pid
+
+    # @!attribute [r] type
+    #   @return [Symbol] lock type, :f_rdlck, :f_wrlck, :f_unlck
+
+    # @!attribute [r] whence
+    #   @return [Symbol] specifies what the offset is relative to, one of :seek_set, :seek_cur or :seek_end
+    #    corresponding to the whence argument to fseek(2) or lseek(2),
+
+    # @!attribute [r] start
+    #  @return [Integer] the offset of the start of the region to which the lock applies, and is given in bytes
+    #   relative to the point specified by #{whence} member.
+
+    # @!attribute [r] len
+    #  @return [Integer] the length of the region to be locked.
+    #
+    #    A value of 0 means the region extends to the end of the file.
+
+    # @!attribute [r] pid
+    #  @return [Integer] the process ID (see Process Creation Concepts) of the process holding the lock.
+    #   It is filled in by calling fcntl with the F_GETLK command, but is ignored when making a lock. If the
+    #   conflicting lock is an open file description lock (see Open File Description Locks), then this field will be
+    #   set to -1.
+  end
+end

data/lib/ffi/gnu_extensions.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+module FFI
+  # Support versioned functions until https://github.com/ffi/ffi/issues/889
+  #
+  # @example
+  #   require 'ffi'
+  #
+  #   module MyLibrary
+  #     extend FFI::Library
+  #
+  #     if FFI::Platform::IS_GNU
+  #       require 'ffi/gnu_extensions'
+  #
+  #       extend(FFI::GNUExtensions)
+  #       # default versions for all functions
+  #       ffi_lib_versions(%w[VERSION_X.3 VERSION_X.2])
+  #     end
+  #
+  #     attach_function :func_one, [:int], :int
+  #     # override default with specific version
+  #     attach_function :func_two, [], :int, versions ['VERSION_X.Y']
+  #
+  #  end
+  module GNUExtensions
+    if FFI::Platform::IS_GNU
+      extend FFI::Library
+      ffi_lib 'libdl'
+
+      # @!method dlopen(library,type)
+      #   @return [FFI::Pointer] library address, possibly NULL
+      attach_function :dlopen, %i[string int], :pointer
+      # @!method dlvsym(handle)
+      #   @return [FFI::Pointer] function address, possibly NULL
+      attach_function :dlvsym, %i[pointer string string], :pointer
+    end
+
+    # @!visibility private
+    def self.extended(mod)
+      mod.extend(DLV) unless mod.respond_to?(:ffi_lib_versions)
+    end
+
+    # Override FFI::Library attach functions with support for dlvsym
+    module DLV
+      # Set the default version(s) for "{attach_function}" (GNU only)
+      # @param [Array<String>|String] versions the default list of versions to search
+      # @return [Array<String>|String]
+      def ffi_lib_versions(versions)
+        @versions = versions
+      end
+
+      # @!visibility private
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+      def attach_function(name, func, args, returns = nil, options = nil)
+        versions = options.delete(:versions) if options.is_a?(Hash)
+
+        return super unless FFI::Platform::IS_GNU
+
+        # Hackety hack duplicated from FFI#attach_function
+        # rubocop:disable Style/ParallelAssignment, Style/TernaryParentheses, Layout/LineLength
+        mname, a2, a3, a4, a5 = name, func, args, returns, options
+        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]
+        # rubocop:enable Style/ParallelAssignment, Style/TernaryParentheses, Layout/LineLength
+
+        versions ||= @versions if defined?(@versions)
+        versions ||= []
+
+        return super if versions.empty?
+
+        function = versions.each do |v|
+          f = find_function_version(cname, v)
+          break f if f
+        end
+
+        # oh well, try the non-version function
+        return super unless function
+
+        arg_types = arg_types.map { |e| find_type(e) }
+        ret_type = find_type(ret_type)
+
+        invoker =
+          if arg_types.length.positive? && arg_types[arg_types.length - 1] == FFI::NativeType::VARARGS
+            VariadicInvoker.new(function, arg_types, ret_type, opts)
+          else
+            Function.new(ret_type, arg_types, function, opts)
+          end
+        invoker.attach(self, mname.to_s)
+        invoker
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+
+      # use dlvsym to find a function address
+      # @param [String|Symbol] cname the function name
+      # @param [String] version the version name
+      # @return [FFI::Pointer] the function address
+      # @return [false] if the function/version combination does not exist in any library
+      def find_function_version(cname, version)
+        ffi_libraries.map(&:name).each do |l|
+          handle = GNUExtensions.dlopen(l, 1)
+          next if handle.null?
+
+          addr = GNUExtensions.dlvsym(handle, cname.to_s, version)
+
+          next if addr.null?
+
+          return addr
+        end
+
+        false
+      end
+    end
+  end
+end