Class: INotify::Event

Inherits:
Object
  • Object
show all
Defined in:
lib/vendor/linux/lib/rb-inotify/event.rb

Overview

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data, notifier) ⇒ Event

Creates an event from a string of binary data. Differs from consume in that it doesn’t modify the string.

Parameters:

  • data (String) —

    The data string

  • notifier (Notifier) —

    The Notifier that fired the event

Raises:

  • (Exception) 


111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/vendor/linux/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 = data[@native.size, @native[:len]].gsub(/\0+$/, '')
  @notifier = notifier
  @watcher_id = @native[:wd]

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

Instance Attribute Details

An integer specifying that this event is related to some other event, which will have the same cookie.

Currently, this is only used for files that are moved within the same directory. Both the ‘:moved_from` and the `:moved_to` events will have the same cookie.

Returns:

  • (Fixnum) 


43
44
45
 
# File 'lib/vendor/linux/lib/rb-inotify/event.rb', line 43

def cookie
  @cookie
end

#name ⇒ String (readonly)

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”`.

Returns:

  • (String) 


28
29
30
 
# File 'lib/vendor/linux/lib/rb-inotify/event.rb', line 28

def name
  @name
end

#notifier ⇒ Notifier (readonly)

The Notifier that fired this event.

Returns:



33
34
35
 
# File 'lib/vendor/linux/lib/rb-inotify/event.rb', line 33

def notifier
  @notifier
end

#related ⇒ Array<Event> (readonly)

A list of other events that are related to this one. Currently, this is only used for files that are moved within the same directory: the ‘:moved_from` and the `:moved_to` events will be related.

Returns:



11
12
13
 
# File 'lib/vendor/linux/lib/rb-inotify/event.rb', line 11

def related
  @related
end

#watcher_id ⇒ Fixnum (readonly)

The id of the Watcher that fired this event.

Returns:

  • (Fixnum) 


49
50
51
 
# File 'lib/vendor/linux/lib/rb-inotify/event.rb', line 49

def watcher_id
  @watcher_id
end

Class Method Details

.consume(data, notifier) ⇒ Event?

Constructs an INotify::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.

Parameters:

  • data (String) —

    The string to be modified

  • notifier (Notifier) —

    The Notifier that fired the event

Returns:

  • (Event, nil) —

    The event, or ‘nil` if the string is empty



98
99
100
101
102
103
 
# File 'lib/vendor/linux/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

Instance Method Details

#absolute_name ⇒ String

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.

Returns:

  • (String) 


66
67
68
69
 
# File 'lib/vendor/linux/lib/rb-inotify/event.rb', line 66

def absolute_name
  return watcher.path if name.empty?
  return File.join(watcher.path, name)
end

#callback! ⇒ Object

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



127
128
129
 
# File 'lib/vendor/linux/lib/rb-inotify/event.rb', line 127

def callback!
  watcher.callback!(self)
end

#flags ⇒ Array<Symbol>

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 was closed, or the watched file or directory was deleted.

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

Returns:

  • (Array<Symbol>) 


86
87
88
 
# File 'lib/vendor/linux/lib/rb-inotify/event.rb', line 86

def flags
  @flags ||= Native::Flags.from_mask(@native[:mask])
end

#size ⇒ Fixnum

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

Returns:

  • (Fixnum) 


135
136
137
 
# File 'lib/vendor/linux/lib/rb-inotify/event.rb', line 135

def size
  @native.size + @native[:len]
end

#watcher ⇒ Watcher

Returns the Watcher that fired this event.

Returns:



54
55
56
 
# File 'lib/vendor/linux/lib/rb-inotify/event.rb', line 54

def watcher
  @watcher ||= @notifier.watchers[@watcher_id]
end