Class | KQueue::Queue |
In: |
lib/rb-kqueue/queue.rb
|
Parent: | Object |
Queue wraps a single instance of kqueue. It‘s possible to have more than one instance, but usually unnecessary.
New event watchers are added to a queue via various `watch_*` methods. For example, \{watch_stream_for_read} watches for a stream to become readable, and \{watch_file} watches for a file to change.
Once watchers are added, \{run} or \{process} can be used to fire events. Note that if any event-causing conditions happen between adding a watcher and running one of these methods, these events are also fired once the methods are called.
@example
# Create the queue queue = KQueue::Queue.new # Run this callback whenever the file path/to/foo.txt is read queue.watch_file("path/to/foo.txt", :write) do puts "Foo.txt was modified!" end # Run this callback whenever this process forks or execs queue.watch_process(Process.pid, :fork, :exec) do |event| # The #flags field of the event object contains the actions that happened puts "This process has #{event.flags.map {|f| f.to_s + "ed"}.join(" and ")}" end # Nothing happens until you run the queue! queue.run
NULL_TIMEOUT | = | Native::TimeSpec.new.tap { |ts| ts[:tv_sec] = 0 |
fd | [R] |
The file descriptor of the kqueue.
@private @return [Fixnum] |
watchers | [R] |
A hash from filter names and idents to {Watcher}s. The kqueue API guarantees that a
(filter, ident) pair uniquely identifies a watcher.
This hash allows events to retrieve their watchers. @private @return [{(Symbol, Fixnum) => Watcher}] |
Blocks until there are one or more events that this queue has watchers registered for. Once there are events, the appropriate callbacks are called and this function returns.
@see run @return [void]
Blocks until there are one or more filesystem events that this notifier has watchers registered for. Once there are events, returns their {Event} objects.
@private
Stop watching for events. That is, if we‘re in a \{run} loop, exit out as soon as we finish handling the current batch of events.
@return [void]
Watches a file or directory for changes. The `flags` parameter specifies which changes will fire events.
The {Event#flags} field contains the changes that caused the event to be fired. {Event#data} and {Event#eof?} are unused.
Note that this only watches a single file. If the file is a direcotry, it will only report changes to the directory itself, not to any files within the directory.
## Flags
`:delete` : The file was deleted.
`:write` : The file was modified.
`:extend` : The size of the file increased.
`:attrib` : Attributes of the file, such as timestamp or permissions, changed.
`:link` : The link count of the file changed.
`:rename` : The file was renamed.
`:revoke` : Access to the file was revoked,
either via the `revoke(2)` system call or because the underlying filesystem was unmounted.
@param path [String] The path to the file or directory. @param flags [Array<Symbol>] Which events to watch for. @yield [event] A block that will be run when the file changes. @yieldparam event [Event] The Event object containing information
about the event that occurred.
@return [Watcher] The Watcher for this event. @raise [SystemCallError] If something goes wrong when registering the Watcher.
Watches for signals to this process. This coexists with other signal facilities, and has lower precedence. Only signals sent to the process, not to a particular thread, will fire events. Event notification happens before normal signal delivery processing.
The {Event#data} field contains the number of times the signal has been generated since the last time the event was fired.
@param signal [String, Fixnum] The name of number of the signal. @yield [event] A block that will be run when the signal is received. @yieldparam event [Event] The Event object containing information
about the event that occurred.
@return [Watcher] The Watcher for this event. @raise [SystemCallError] If something goes wrong when registering the Watcher.
Watches a process for changes. The `flags` parameter specifies which changes will fire events.
The {Event#flags} field contains the changes that caused the event to be fired. {Event#data} and {Event#eof?} are unused.
## Flags
`:exit` : The process has exited.
`:fork` : The process has created a child process via `fork(2)` or similar.
`:exec` : The process has executed a new process via `exec(2)` or similar.
`:signal` : The process was sent a signal.
This is only supported under Darwin/OS X.
`:reap` : The process was reaped by the parent via `wait(2)` or similar.
This is only supported under Darwin/OS X.
`:track` : Follow the process across `fork(2)` calls.
{Event#flags} for the parent process will contain `:fork`, while {Event#flags} for the child process will contain `:child`. If the system was unable to attach an event to the child process, {Event#flags} will contain `:trackerr`. This is not supported under Darwin/OS X.
@param pid [Fixnum] The id of the process. @param flags [Array<Symbol>] Which events to watch for. @yield [event] A block that will be run when the process changes. @yieldparam event [Event] The Event object containing information
about the event that occurred.
@return [Watcher] The Watcher for this event. @raise [SystemCallError] If something goes wrong when registering the Watcher.
Watches a socket and produces an event when there‘s data available to read.
Sockets which have previously had `Socket#listen` called fire events when there is an incoming connection pending. In this case, {Event#data} contains the size of the listen backlog.
Other sockets return when there is data to be read, subject to the SO_RCVLOWAT value of the socket buffer. This may be overridden via the `low_water` parameter, which sets a new low-water mark. In this case, {Event#data} contains the number of bytes of protocol data available to read.
If the read direction of the socket has shut down, then {Event#eof?} is set. It‘s possible for {Event#eof?} to be set while there‘s still data pending in the socket buffer.
Note that this isn‘t compatible with JRuby unless a native-code file descriptor is passed in. This means the file descriptor must be returned by an FFI-wrapped C function.
@param fd [Socket, Fixnum] A Ruby Socket, or the file descriptor
for a native Socket.
@param low_water [Fixnum] The low-water mark for new data. @yield [event] A block that will be run when the specified socket
has data to read.
@yieldparam event [Event] The Event object containing information
about the event that occurred.
@return [Watcher] The Watcher for this event. @raise [SystemCallError] If something goes wrong when registering the Watcher.
Watches a socket and produces an event when it‘s possible to write. The {Event#data} field is set to the amount of space remaining in the write buffer.
When an event is fired is subject to the subject to the SO_RCVLOWAT value of the socket buffer. This may be overridden via the `low_water` parameter, which sets a new low-water mark.
If the write direction of the socket has shut down, then {Event#eof?} is set. It‘s possible for {Event#eof?} to be set while there‘s still data pending in the socket buffer.
Note that this isn‘t compatible with JRuby unless a native-code file descriptor is passed in. This means the file descriptor must be returned by an FFI-wrapped C function.
@param fd [Socket, Fixnum] A Ruby Socket, or the file descriptor
for a native Socket.
@param low_water [Fixnum] The low-water mark for new data. @yield [event] A block that will be run when it‘s possible
to write to the specified socket.
@yieldparam event [Event] The Event object containing information
about the event that occurred.
@return [Watcher] The Watcher for this event. @raise [SystemCallError] If something goes wrong when registering the Watcher.
Watches a stream and produces an event when there‘s data available to read.
This can watch files, pipes, fifos, and BPF devices. For files, an event is fired whenever the file pointer is not at the end of the file, and the {Event#data} field is set to the offset from the current position to the end of the file. {Event#data} may be negative.
For pipes and fifos, an event is fired whenever there‘s data to read. The {Event#data} field is set to the number of bytes available. When the last writer disconnects, {Event#eof?} will be set.
For BPF devices (not supported under Darwin/OS X), an event is fired when the BPF buffer is full, the BPF timeout has expired, or when the BPF has "immediate mode" enabled and there is data to read. The {Event#data} field is set to the number of bytes available.
Note that this isn‘t compatible with JRuby unless a native-code file descriptor is passed in. This means the file descriptor must be returned by an FFI-wrapped C function.
@param fd [IO, Fixnum] A Ruby IO stream, or the file descriptor
for a native IO stream.
@yield [event] A block that will be run when the specified stream
has data to read.
@yieldparam event [Event] The Event object containing information
about the event that occurred.
@return [Watcher] The Watcher for this event. @raise [SystemCallError] If something goes wrong when registering the Watcher.
Watches a stream and produces an event when it‘s possible to write to the stream.
This can watch pipes and fifos. The {Event#data} field is set to the amount of space remaining in the write buffer. When the reader disconnects, {Event#eof?} will be set.
Note that this isn‘t compatible with JRuby unless a native-code file descriptor is passed in. This means the file descriptor must be returned by an FFI-wrapped C function.
@param fd [IO, Fixnum] A Ruby IO stream, or the file descriptor
for a native IO stream.
@yield [event] A block that will be run when the specified stream
has data to read.
@yieldparam event [Event] The Event object containing information
about the event that occurred.
@return [Watcher] The Watcher for this event. @raise [SystemCallError] If something goes wrong when registering the Watcher.
Sets up a watcher that fires an event once every specified interval.
The {Event#data} field contains the number of times the interval has passed since the last time the event was fired.
@param time [Number] The interval, in seconds. @yield [event] A block that will be run when the interval passes. @yieldparam event [Event] The Event object containing information
about the event that occurred.
@return [Watcher] The Watcher for this event. @raise [SystemCallError] If something goes wrong when registering the Watcher.