NAME

Bot::Cobalt::Core::Role::Timers

SYNOPSIS

## From a Cobalt plugin:
my $new_id = $core->timer_set( 60,
  {
    Event => 'my_timed_event',
    Args  => [ $one, $two ],
    Alias => $core->get_plugin_alias($self),
  }
);

$core->timer_set( 60,
  {
    Event => 'my_timed_event',
    Args  => [ $one, $two ],
  },
  'MY_NAMED_TIMER'
);

$core->timer_del( $timer_id );
$core->timer_del_alias( $core->get_plugin_alias($self) );

my $timer_item = $core->timer_get( $timer_id );
my @active = $core->timer_get_alias( $core->get_plugin_alias($self) );
  

DESCRIPTION

Bot::Cobalt core interface role for managing a pool of timers living in a TimerPool hash.

This is consumed by Bot::Cobalt::Core to provide timer manipulation methods to the plugin pipeline.

METHODS

timer_set

The timer_set method adds a new timer to the hashref provided by TimerPool in the consuming class (usually Bot::Cobalt::Core).

## Supply a Bot::Cobalt::Timer object:
$core->timer_set( $timer_obj );

## Supply a hashref containing options:
$core->timer_set( $secs, $opts_ref );
$core->timer_set( $secs, $opts_ref, $timer_id );

An already-constructed Bot::Cobalt::Timer object can be passed in; see the Bot::Cobalt::Timer documentation for details on constructing a timer object.

More frequently, plugins pass in a hash reference containing event options and let timer_set construct a Bot::Cobalt::Timer on its own. This is the interface documented here.

timer_set will return the new timer's ID on success; a send_event will be called for event "new_timer".

Basic timers

The most basic timer is fire-and-forget with no alias tag and no preservation of timer ID:

## From a Cobalt plugin
## Trigger Bot_myplugin_timed_ev with no args in 30 seconds
$core->timer_set( 30, 'myplugin_timed_ev' );
## Same as:
$core->timer_set( 30, { Event => 'myplugin_timed_ev'  } );

A more sophisticated timer will probably have some arguments specified:

$core->timer_set( 30,
  {
    Event => 'myplugin_timed_ev',
    Args  => [ $one, $two ],
  },
);

If this is not a named timer, a unique timer ID will be created:

my $new_id = $core->timer_set(30, { Event => 'myplugin_timed_ev' });

When used from Cobalt plugins, a timer should usually have an alias specified; this makes it easier to clear your pending timers from a Cobalt_unregister event using "timer_del_alias", for example.

## From a Cobalt plugin
## Tag w/ our current plugin alias from Bot::Cobalt::Core
my $new_id = $core->timer_set( 30,
  {
    Event => 'myplugin_timed_ev',
    Args  => [ $one, $two ],
    Alias => $core->get_plugin_alias($self),
  }
);

Named timers

If a timer is intended to be globally unique within this TimerPool or the timer ID is generated by some other method, it can be specified in timer_set. Existing timers with the same ID will be replaced.

$core->timer_set( 30, 
  { 
    Event => 'myplugin_timed_ev',
    Args  => [ ],
  },
  'MY_NAMED_TIMER',
);

(This, of course, makes life difficult if your plugin is intended to be instanced more than once.)

Message timers

If a timer is simply intended to send some message or action to an IRC context, the msg and action types can be used for convenience:

$core->timer_set( 30,
  {
    Alias   => $core->get_plugin_alias($self),
    Type    => 'msg',
    Context => $context,
    Target  => $channel,
    Text    => $string,
  },
);

timer_set_hashref

timer_set_hashref is the method called by "timer_set" when it is not passed a preexisting Bot::Cobalt::Timer object; you would not normally use this method directly.

timer_del

Deletes a timer by timer ID.

Returns the deleted timer item on success.

Calls a send_event for event "deleted_timer".

timer_del_alias

Deletes a timer by tagged alias.

Returns the list of deleted timer IDs in list context or the number of deleted timers in scalar context.

A send_event is called for "deleted_timer" events for every removed timer.

timer_get

Retrieves the Bot::Cobalt::Timer object for the specified timer ID.

This can be useful for tweaking active timers.

timer_get_alias

Returns all timer IDs in the pool belonging to the specified alias tag.

Returns a list of timer IDs. In scalar context, returns an array reference.

timer_gen_unique_id

Generates a unique (guaranteed not to exist in the consumer's TimerPool) randomized ID for a timer.

You would not normally call this method directly.

EVENTS

new_timer

Issued when a timer is set.

Only argument provided is the timer ID.

deleted_timer

Issued when a timer is deleted.

Arguments are the timer ID and the deleted item object, respectively.

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>

http://www.cobaltirc.org