NAME

Sprocket::Plugin - Base class for Sprocket plugins

SYNOPSIS

  use Sprocket qw( Plugin );
  use base qw( Sprocket::Plugin );

  sub new {
      shift->SUPER::new(
          name => 'MyPlugin',
          @_
      );
  }

  sub as_string {
      __PACKAGE__;
  }

  ...

ABSTRACT

This is a base class for Sprocket plugins. It provides several default methods for easy plugin implementation.

NOTES

A plugin can define any of the methods below. All are optional, but a plugin should have a conncted and a receive method for it to function. See the Sprocket site for examples. http://sprocket.cc/ Plugins should use the template in the SYNOPSIS.

Also, this module is a subclass of Class::Accessor::Fast, so subclasses of Sprocket::Plugin can create accessors like so (in your new() method):

  __PACKAGE__->mk_accessors( qw( foo bar baz ) );

EVENTS

Server Event Methods

These are methods that can be defined in a plugin for Sprocket server instances

local_accept

Called with ( $self, $server, $con, $socket ) Defining this method is optional. The default behavior is to accept the connection. You can call $con->reject() or $con->accept() to reject or accept a connection. You can also call $self->take_connection( $con ); in this phase. See Sprocket::Connection for more information on the accept and reject methods.

local_connected

Called with ( $self, $server, $con, $socket ) This is the last chance for a plugin to take a connection with $self->take_connection( $con ); You should apply your filters for the connection in this method. See Sprocket::Connection for details on how to access the connection's filters.

local_receive

Called with ( $self, $server, $con, $data ) $data is the data from the filter applied to the connection.

Note: A connection's active time doesn't update automaticly for this event. You can call $con->active(), see Sprocket::Connection.

local_disconnected

Called with ( $self, $server, $con, $error ) If error is true, then $operation, $errnum, and $errstr will also be defined after $error. If a connection was closed with $con->close() then $error will be false. If a connection was closed remotely but without an error then $error will be true, but $errnum will be 0. For more details, see ErrorEvent in POE::Wheel::ReadWrite.

local_error

Called with ( $self, $server, $operation, $errnum, $errstr ) This is only called when there is an error with the server wheel, like a bind error. ( $errnum will == EADDRINUSE, after: use Errno qw( EADDRINUSE ); ) The default behavior will be to shutdown the server if there is a bind error.

local_time_out

Called with ( $self, $server, $con, $time ) A time out occurred on the connection. This means the $con->active_time + $con->time_out is less than $time. You can choose to $con->close() or not. The default behavior is to close the connection. This event will only occur if you have set a time out with $con->set_time_out( $seconds )

local_shutdown

Called with ( $self, $server, $con ) This is currently only called when a soft shutdown is initiated. You should make cleanup arrangements and close the connection asap. The server will wait for all connections to close. See the shutdown command in Sprocket::Server, and Sprocket::Client.

Client Event Methods

These are methods that can be defined in a plugin for Sprocket client instances

remote_accept

Why is there an accept method for client connections?! Well, good question. This method is here to allow you to set the filters and blocksize using the $con-accept method. See Sprocket::Connection

See local_accept.

remote_connected

See local_connected.

remote_receive

See local_receive.

remote_disconnected

See local_disconnected. You can call $con->reconnect() to attempt to reconnect to the host.

remote_connect_error

Called with ( $self, $client, $con ) If a connection wasn't attempted due to a DNS issue, $response_error, and $response_obj from POE::Component::DNS will follow $con. The remote_disconnected event will not be called. You can call $con->reconnect() to attempt to reconnect to the host.

remote_time_out

Called with ( $self, $client, $con, $time ) A time out occurred on the connection. This means the $con->active_time + $con->time_out is less than $time. You can choose to $con->close() or not. The default behavior is to close the connection. This event will only occur if you have set a time out with $con->set_time_out( $seconds )

remote_shutdown

See local_shutdown.

METHODS

$self->con_id_list

Returns a list of connection ids currently active conenctions taken by the plugin. Use $sprocket->get_connection() to get the connection reference. Note: con_id_list in a scalar context will return an array ref

  foreach ( $self->con_id_list ) {
      if ( my $con = $sprocket->get_connection( $_ ) ) {
          $con->send( "you are client:".$con->ID );
      }
  }

$self->take_connection( $con )

Assigns the connection to your plugin. Usually done during the accept or connect phase.

release_connection( $con );

spread_subscribe( [ 'group1', 'group2' ] );

spread_unsubscribe( [ 'group1', 'group2' ] );

spread_publish( [ 'group1', 'group2' ], $message, @etc );

SEE ALSO

Sprocket, Sprocket::Connection, Sprocket::AIO, Sprocket::Server, Sprocket::Client, Sprocket::Local

AUTHOR

David Davis <xantus@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2006-2007 by David Davis

See Sprocket for license information.