=pod

=encoding utf-8

=head1 NAME

Net::BitTorrent::Emitter - Base class for event-driven objects

=head1 SYNOPSIS

    class My::Class : isa(Net::BitTorrent::Emitter) { ... }

    my $obj = My::Class->new;
    $obj->on( 'my_event' => sub ($self, @args) { ... } );

=head1 DESCRIPTION

This class provides a simple event emitter mechanism. It is used as a base class for many components in
Net::BitTorrent.

=head1 METHODS

=head2 C<on( $event, $callback )>

Registers an event listener.

    $obj->on('connected', sub ($obj, $peer) {
        say "Connected to " . $peer->ip;
    });

This method adds a callback to be executed when the specified event is emitted. It returns the emitter object for
chaining.

Expected parameters:

=over

=item C<$event>

The name of the event to listen for.

=item C<$callback>

The code reference to execute. It receives the emitter object as the first argument, followed by any arguments passed
to the emit call.

=back

=head2 C<set_parent_emitter( $parent )>

Sets the parent emitter for event bubbling.

    $obj->set_parent_emitter( $parent );

This method allows events emitted by this object to bubble up to a parent emitter.

Expected parameters:

=over

=item C<$parent>

 The parent L<Net::BitTorrent::Emitter> object.

=back

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=head1 COPYRIGHT

Copyright (C) 2008-2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

=cut
