NAME
    Sim::Dispatcher - Event dispatcher for Sim

VERSION
    This document describes Sim::Dispatcher 0.02 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 <agentzh@gmail.com>

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.

