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