Jon Portnoy > Bot-Cobalt > Bot::Cobalt::Core::Role::Timers



Annotate this POD

View/Report Bugs
Module Version: 0.017007   Source  




  ## 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 ],
  $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) );


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.



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  => [ ],

(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 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.


Deletes a timer by timer ID.

Returns the deleted timer item on success.

Calls a send_event for event "deleted_timer".


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.


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

This can be useful for tweaking active timers.


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.


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.



Issued when a timer is set.

Only argument provided is the timer ID.


Issued when a timer is deleted.

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


Jon Portnoy <>

syntax highlighting: