Dispatch::Source Class

Watson1978 edited this page Jul 14, 2012 · 2 revisions

Dispatch::Source monitors a variety of system objects and events including file descriptors, processes, virtual filesystem nodes, signals and timers.

Constants in Dispatch::Source class

Here is the constants which are used as type when create a Dispatch::Source instance.

Constants Meaning
Dispatch::Source::DATA_ADD It coalesces data obtained via calls to Dispatch::Source#<<.
Dispatch::Source::DATA_OR It coalesces data obtained via calls to Dispatch::Source#<<.
Dispatch::Source::PROC It monitors an external process for events.
Dispatch::Source::SIGNAL It monitors the current process for signals.
Dispatch::Source::VNODE It monitors a file descriptor for events.
Dispatch::Source::READ It monitors a file descriptor for pending bytes available to be read.
Dispatch::Source::WRITE It monitors a file descriptor for available buffer space to write bytes.

Here is the constants which are used as mask of Dispatch::Source::PROC.

Constants Meaning
Dispatch::Source::PROC_EXIT The process has exited.
Dispatch::Source::PROC_FORK The process has created one or more child processes.
Dispatch::Source::PROC_EXEC The process has become another executable image.
Dispatch::Source::PROC_SIGNAL A Unix signal was delivered to the process.

Here is the constants which are used as mask of Dispatch::Source::VNODE.

Constants Meaning
Dispatch::Source::VNODE_DELETE The file-system object was deleted.
Dispatch::Source::VNODE_WRITE The file-system object data changed.
Dispatch::Source::VNODE_EXTEND The file-system object changed in size.
Dispatch::Source::VNODE_ATTRIB The file-system object metadata changed.
Dispatch::Source::VNODE_LINK The file‐system object link count changed.
Dispatch::Source::VNODE_RENAME The file‐system object was renamed.
Dispatch::Source::VNODE_REVOKE The file-system object was revoked.

Methods in Dispatch::Source class

Dispatch::Source.new

Creates a new Dispatch::Source object.

  • new(type, handle, mask, queue) { ... } -> Source
    • [PARAM] type:
      • The type of the dispatch source.
    • [PARAM] handle:
      • The handle to monitor. If passeed DATA_ADD or DATA_OR in type, specify the 0 in this argument.
    • [PARAM] mask:
      • The mask of flags.
    • [PARAM] queue:
      • The dispatch queue to which the event handler block is submitted.
    • [RETURN]
      • Returns a Dispatch::Source instance.

Dispatch::Source.timer

Creates a new Dispatch::Source object for timer event. This method is declared in GCD API as dispatch_source_set_timer.

  • timer(delay, interval, leeway, queue) { ... } -> Source
    • [PARAM] delay:
      • The start time of the timer.
    • [PARAM] interval:
      • The second interval for the timer.
    • [PARAM] leeway:
      • The amount of time, in seconds, that the system can defer the timer.
    • [PARAM] queue:
      • The dispatch queue to which the event handler block is submitted.
    • [RETURN]
      • Returns a Dispatch::Source instance.
gcdq = Dispatch::Queue.new('sample')
timer = Dispatch::Source.timer(0.5, 1, 0.5, gcdq) do |s|
  puts "Wake up!"
end

sleep 3

Dispatch::Source#cancelled?

Tests whether the given dispatch source has been canceled.

  • cancelled? -> bool
    • [RETURN]
      • Returns a true if cancelled, otherwise false.

Dispatch::Source#cancel!

Asynchronously cancels the dispatch source, preventing any further invocation of its event handler block.

  • cancel!
gcdq = Dispatch::Queue.new('sample')
timer = Dispatch::Source.timer(1, 0.5, 0, gcdq) do |s|
  puts "Wake up!"
end

sleep 2

timer.cancel!
p timer.cancelled? # => true

sleep 1

Dispatch::Source#handle

Returns the underlying Ruby handle for the dispatch source.

  • handle
    • [RETURN]
      • Returns a handle.

Dispatch::Source#mask

Returns a Number representing the mask argument, corresponding to the flags set when the source was created.

  • mask
    • [RETURN]
      • Returns a mask.

Dispatch::Source#data

Returns a Number containing currently pending data for the dispatch source.

  • data
    • [RETURN]
      • Returns a pending data.

The return value should be interpreted according to the type of the dispatch source, and can be one of the following.

Type Returning a data
Dispatch::Source::DATA_ADD The data which sent by Dispatch::Source#<<.
Dispatch::Source::DATA_OR The data which sent by Dispatch::Source#<<.
Dispatch::Source::PROC The constant which is one of Dispatch::Source::PROC_EXIT, Dispatch::Source::PROC_FORK, Dispatch::Source::PROC_EXEC or Dispatch::Source::PROC_SIGNAL.
Dispatch::Source::SIGNAL The signal number.
Dispatch::Source::READ The pending bytes available to be read.
gcdq = Dispatch::Queue.new('sample')
src = Dispatch::Source.new(Dispatch::Source::DATA_ADD, 0, 0, gcdq) do |s|
  puts s.data
end
src << 1
sleep 0.5

Dispatch::Source#<<

Intended only for use with the Dispatch::Source::DATA_ADD and Dispatch::Source::DATA_OR source types, calling this function will atomically ADD or logical OR the count into the source's data, and trigger delivery of the source's event handler.

  • << data