NAME

Bot::Cobalt::Timer - Cobalt timer objects

SYNOPSIS

  my $timer = Bot::Cobalt::Timer->new(
    event  => 'my_timed_event',
    args   => [ $one, $two ],
  );
  
  $timer->delay(30);
  
  ## Add this instance to Core's TimerPool, for example:
  $core->timer_set( $timer );

DESCRIPTION

A Bot::Cobalt::Timer instance represents a single timed event.

These are usually constructed for use by the Bot::Cobalt::Core TimerPool; also see "timer_set" in Bot::Cobalt::Core::Role::Timers.

  my $timer = Bot::Cobalt::Timer->new;

By default, timers that are executed will fire against the Bot::Cobalt::Core singleton; you can pass in a different 'core =>' specification if needed.

METHODS

Timer settings

at

The absolute time that this timer is supposed to fire (epoch seconds).

This is normally set automatically when "delay" is called.

(If it is tweaked manually, "delay" is irrelevant information.)

delay

The time this timer is supposed to fire expressed in seconds from the time it was set.

(Sets "at" to time() + delay)

event

The name of the event that should be fired via send_event when this timer is executed.

args

A List::Objects::WithUtils::Array containing any arguments attached to the "event".

id

This timer's unique identifier, used as a key in timer pools.

Note that a unique random ID is added when the Timer object is passed to "timer_set" in Bot::Cobalt::Core::Role::Timers if no id is explicitly specified.

alias

The alias tag attached to this timer. Defaults to caller()

type

The type of event.

Valid types as of this writing are msg, action, and event.

msg and action types require "context", "text", and "target" attributes be specified.

If no type has been specified for this timer, type() returns our best guess; for timed events carrying a "context" and "target" the default is msg.

This is used to set up proper event names for special timer types.

context

msg and action timer types only

The server context for an outgoing msg or action.

See "type"

text

msg and action timer types only

The text string to send with an outgoing msg or action.

See "type"

target

msg and action timer types only

The target channel or nickname for an outgoing msg or action.

See "type"

Execution

A timer object can be instructed to execute as long as it was provided a proper core object at construction time -- this is normally Bot::Cobalt::Core, but any class that can send_event will do.

is_ready

Returns boolean true if the timer is ready to execute; in other words, if the specified "at" is reached.

execute_if_ready

"execute" the timer if "is_ready" is true.

execute

Execute the timer; if our core object can send_event, the timer's event is broadcast. Otherwise the timer will warn and return.

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>