NAME
Sim::Dispatcher - Event dispatcher for Sim
VERSION
This document describes Sim::Dispatcher 0.03 released on June 2, 2007.
SYNOPSIS
use Sim::Dispatcher;
use Sim::Clock;
my $clock = Sim::Clock->new;
# you can also use your own Clock instance here
my $engine = Sim::Dispatcher->new(clock => $clock);
# Example 1: Static scheduling
$engine->schedule(
0 => sub { print $engine->now, ": morning!\n" },
1 => sub { print $engine->now, ": afternoon!\n" },
5 => sub { print $engine->now, ": night!\n" },
);
$engine->run( duration => 50 );
# or Sim::Dispatcher->run( fires => 5 );
$engine->reset();
# Example 2: Dynamic (recursive) scheduling
my ($count, $handler);
# event handler:
$handler = sub {
$count++;
my $time_for_next = $engine->now() + 2;
$engine->schedule(
$time_for_next => $handler,
);
};
# only schedule the "seed" event
$engine->schedule(
0.5 => $handler,
);
$engine->run( fires => 5 );
print "count: $count\n"; # 5
print "now: ", $engine->now(), "\n"; # 8
DESCRIPTION
This class implements the most important component in the whole Sim
library, the event dispatcher. Basically, every activites should be
coordinated by this dispatcher. Every other objects in a simulator
either register an event scheduled to happen at some point in the
"future", or iterate through the dispatching steps.
METHODS
"$obj = Sim::Dispatcher->new( clock => $clock)"
Object constructor accepting one mandatory named argument $clock
which is an instance of classes like Sim::Clock.
"$obj->schedule( $time => $handle, ... )"
You can use this method to register events scheduled for the future,
where $time is the timestamp and $handle is an anonymous sub which
will be invoked by the dispatcher when the simulation time is at
$time.
"$obj->run( duration => $time, fires => $count )"
Runs the dispatcher according to the time duration and event firing
count. both of these named parameters are optional. When none is
specified, "fires => 100_000_000" will be assumed.
"$obj->fire_next()"
This method allows you to iterate through the dispatcher running
process yourself. You should only call "fire_next" by hand if you've
found the limitation criteria given by the "run" method can't fit
your needs.
"$obj->now()"
Reads the value of the simulation time.
"$obj->time_of_next()"
Gets the timestamp of the next (or nearest) coming event, which is
always a bit greater or equal to "now".
"$obj->reset()"
Clears the internal event queue of the dispatcher and resets the
internal simulation clock too.
CONCURRENCY ISSUES
If two events have exactly the same timestamp, say, 1.5, then the one
registered earlier will be fired first.
AUTHOR
Agent Zhang <
[email protected]>
COPYRIGHT
Copyright 2006, 2007 by Agent Zhang. All rights reserved.
This library is free software; you can modify and/or modify it under the
same terms as Perl itself.
SEE ALSO
Sim::Clock, Sim.
