Class: Cinch::Timer

Inherits:
Object
  • Object
show all
Includes:
Helpers
Defined in:
lib/cinch/timer.rb

Overview

Note:

It is possible to directly create instances of this class, but the referenced methods should suffice.

Timers are used for executing code in the future, either repeatedly or only once.

In Cinch, two ways for creating timers are available:

  • The first way is by declaring them for a plugin, in which case they will start as soon as the bot connects to a server.

  • The second way is to dynamically create new timers in response to user input. A common example for this is an alarm clock plugin, which has to execute at a specific time.

See Also:

Since:

  • 2.0.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Helpers

#Channel, #Format, #Sanitize, #Target, #Timer, #Unformat, #User, #debug, #error, #exception, #fatal, #incoming, #info, #log, #outgoing, #rescue_exception, sanitize, #warn

Constructor Details

#initialize(bot, options, &block) ⇒ Timer

Returns a new instance of Timer.

Parameters:

  • bot (Bot) —

    The instance of Bot the timer is associated with

  • options (Hash) —

    a customizable set of options

Options Hash (options):

  • :interval (Numeric) —

    The interval (in seconds) of the timer

  • :shots (Integer) — default: Float::INFINITY —

    How often should the timer fire?

  • :threaded (Boolean) — default: true —

    If true, each invocation will be executed in a thread of its own.

  • :start_automatically (Boolean) — default: true —

    If true, the timer will automatically start after the bot finished connecting.

  • :stop_automaticall (Boolean) — default: true —

    If true, the timer will automatically stop when the bot disconnects.

Since:

  • 2.0.0



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/cinch/timer.rb', line 64

def initialize(bot, options, &block)
  options = {:threaded => true, :shots => Float::INFINITY, :start_automatically => true, :stop_automatically => true}.merge(options)

  @bot        = bot
  @interval   = options[:interval].to_f
  @threaded   = options[:threaded]
  @orig_shots = options[:shots]
  # Setting @shots here so the attr_reader won't return nil
  @shots      = @orig_shots
  @block      = block

  @started = false
  @thread_group = ThreadGroup.new

  if options[:start_automatically]
    @bot.on :connect, //, self do |m, timer|
      timer.start
    end
  end

  if options[:stop_automatically]
    @bot.on :disconnect, //, self do |m, timer|
      timer.stop
    end
  end
end

Instance Attribute Details

#block ⇒ Proc (readonly)

Returns:

  • (Proc)

Since:

  • 2.0.0



35
36
37
 
# File 'lib/cinch/timer.rb', line 35

def block
  @block
end

#bot ⇒ Bot (readonly)

Returns:

Since:

  • 2.0.0



25
26
27
 
# File 'lib/cinch/timer.rb', line 25

def bot
  @bot
end

#interval ⇒ Numeric

Returns The interval (in seconds) of the timer.

Returns:

  • (Numeric) —

    The interval (in seconds) of the timer

Since:

  • 2.0.0



28
29
30
 
# File 'lib/cinch/timer.rb', line 28

def interval
  @interval
end

#shots ⇒ Integer

Returns The remaining number of shots before this timer will stop. This value will automatically reset after restarting the timer.

Returns:

  • (Integer) —

    The remaining number of shots before this timer will stop. This value will automatically reset after restarting the timer.

Since:

  • 2.0.0



43
44
45
 
# File 'lib/cinch/timer.rb', line 43

def shots
  @shots
end

#started ⇒ Boolean (readonly) Also known as: started?

Returns:

  • (Boolean)

Since:

  • 2.0.0



38
39
40
 
# File 'lib/cinch/timer.rb', line 38

def started
  @started
end

#thread_group ⇒ ThreadGroup (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (ThreadGroup)

Since:

  • 2.0.0



49
50
51
 
# File 'lib/cinch/timer.rb', line 49

def thread_group
  @thread_group
end

#threaded ⇒ Boolean Also known as: threaded?

Returns If true, each invocation will be executed in a thread of its own.

Returns:

  • (Boolean) —

    If true, each invocation will be executed in a thread of its own.

Since:

  • 2.0.0



32
33
34
 
# File 'lib/cinch/timer.rb', line 32

def threaded
  @threaded
end

Instance Method Details

#start

This method returns an undefined value.

Start the timer

Since:

  • 2.0.0



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/cinch/timer.rb', line 99

def start
  return if @started

  @bot.loggers.debug "[timer] Starting timer #{self}"

  @shots = @orig_shots

  @thread_group.add Thread.new {
    while @shots > 0 do
      sleep @interval
      if threaded?
        Thread.new do
          rescue_exception do
            @block.call
          end
        end
      else
        rescue_exception do
          @block.call
        end
      end

      @shots -= 1
    end
  }

  @started = true
end

#stop

This method returns an undefined value.

Stop the timer

Since:

  • 2.0.0



131
132
133
134
135
136
137
138
 
# File 'lib/cinch/timer.rb', line 131

def stop
  return unless @started

  @bot.loggers.debug "[timer] Stopping timer #{self}"

  @thread_group.list.each { |thread| thread.kill }
  @started = false
end

#stopped? ⇒ Boolean

Returns:

  • (Boolean)

Since:

  • 2.0.0



92
93
94
 
# File 'lib/cinch/timer.rb', line 92

def stopped?
  !@started
end

#to_s ⇒ String

Returns:

Since:

  • 2.0.0



141
142
143
 
# File 'lib/cinch/timer.rb', line 141

def to_s
  "<Cinch::Timer %s/%s shots, %ds interval, %sthreaded, %sstarted, block: %s>" % [@orig_shots - @shots, @orig_shots, @interval, @threaded ? "" : "not ", @started ? "" : "not ", @block]
end