class INotify::Event

An event caused by a change on the filesystem. Each {Watcher} can fire many events, which are passed to that watcher's callback.

Attributes

name[R]

The name of the file that the event occurred on. This is only set for events that occur on files in directories; otherwise, it's `“”`. Similarly, if the event is being fired for the directory itself the name will be `“”`

This pathname is relative to the enclosing directory. For the absolute pathname, use {#absolute_name}. Note that when the `:recursive` flag is passed to {Notifier#watch}, events in nested subdirectories will still have a `#name` field relative to their immediately enclosing directory. For example, an event on the file `“foo/bar/baz”` will have name `“baz”`.

@return [String]

notifier[R]

The {Notifier} that fired this event.

@return [Notifier]

watcher_id[R]

The {Watcher#id id} of the {Watcher} that fired this event.

@private @return [Fixnum]

Public Class Methods

consume(data, notifier) click to toggle source

Constructs an {Event} object from a string of binary data, and destructively modifies the string to get rid of the initial segment used to construct the Event.

@private @param data [String] The string to be modified @param notifier [Notifier] The {Notifier} that fired the event @return [Event, nil] The event, or `nil` if the string is empty

# File lib/rb-inotify/event.rb, line 98
def self.consume(data, notifier)
  return nil if data.empty?
  ev = new(data, notifier)
  data.replace data[ev.size..-1]
  ev
end
new(data, notifier) click to toggle source

Creates an event from a string of binary data. Differs from {Event.consume} in that it doesn't modify the string.

@private @param data [String] The data string @param notifier [Notifier] The {Notifier} that fired the event

# File lib/rb-inotify/event.rb, line 111
def initialize(data, notifier)
  ptr = FFI::MemoryPointer.from_string(data)
  @native = Native::Event.new(ptr)
  @related = []
  @cookie = @native[:cookie]
  @name = fix_encoding(data[@native.size, @native[:len]].gsub(/\0+$/, ''))
  @notifier = notifier
  @watcher_id = @native[:wd]

  raise QueueOverflowError.new("inotify event queue has overflowed.") if @native[:mask] & Native::Flags::IN_Q_OVERFLOW != 0
end

Public Instance Methods

absolute_name() click to toggle source

The absolute path of the file that the event occurred on.

This is actually only as absolute as the path passed to the {Watcher} that created this event. However, it is relative to the working directory, assuming that hasn't changed since the watcher started.

@return [String]

# File lib/rb-inotify/event.rb, line 66
def absolute_name
  return watcher.path if name.empty?
  return File.join(watcher.path, name)
end
callback!() click to toggle source

Calls the callback of the watcher that fired this event, passing in the event itself.

@private

# File lib/rb-inotify/event.rb, line 127
def callback!
  watcher.callback!(self)
end
flags() click to toggle source

Returns the flags that describe this event. This is generally similar to the input to {Notifier#watch}, except that it won't contain options flags nor `:all_events`, and it may contain one or more of the following flags:

`:unmount` : The filesystem containing the watched file or directory was unmounted.

`:ignored` : The {#watcher watcher} was closed, or the watched file or directory was deleted.

`:isdir` : The subject of this event is a directory.

@return [Array<Symbol>]

# File lib/rb-inotify/event.rb, line 86
def flags
  @flags ||= Native::Flags.from_mask(@native[:mask])
end
size() click to toggle source

Returns the size of this event object in bytes, including the {#name} string.

@return [Fixnum]

# File lib/rb-inotify/event.rb, line 135
def size
  @native.size + @native[:len]
end
watcher() click to toggle source

Returns the {Watcher} that fired this event.

@return [Watcher]

# File lib/rb-inotify/event.rb, line 54
def watcher
  @watcher ||= @notifier.watchers[@watcher_id]
end

Private Instance Methods

fix_encoding(name) click to toggle source
# File lib/rb-inotify/event.rb, line 141
def fix_encoding(name)
  name.force_encoding('filesystem') if name.respond_to?(:force_encoding)
  name
end