/ 
bioperl-1.2.2
/ Bio::Tools::StateMachine::AbstractStateMachine

NAME

Bio::Tools::StateMachine::AbstractStateMachine - Abstract state machine object

SYNOPSIS

Here is a portion of an implementation. For the full example, see examples/state-machine.pl in the Bioperl distribution.

package SimpleStateMachine;

use Bio::Root::Root;
use Bio::Tools::StateMachine::AbstractStateMachine qw($INITIAL_STATE 
							  $FINAL_STATE);
use vars qw( @ISA );

@ISA = qw( Bio::Root::Root
	   Bio::Tools::StateMachine::AbstractStateMachine );

my @state_transitions = (  [ $INITIAL_STATE, 'State1'],
			       [ 'State1', 'State2' ],
			       [ 'State2', $FINAL_STATE]
				);
sub new {
   my($caller,@args) = @_;
   my $self = $caller->SUPER::new( @args);
   $self->_init_state_machine( -transition_table => \@state_transitions );
   return $self;
}

DESCRIPTION

AbstractStateMachine provides a generic framework for representing a state machine. This is not an event-based framework where you register handlers to be called when certain events occur. Instead, it provides a set of methods that define the basic logic of an object that has state behavior, that logic being:

1. Check for whether or not a new state has occurred in the external world.
2. If so, change the state of the machine to the new state.
3. Otherwise, keep checking current conditions for a new state.
4. Stop checking for new states if we reach the final state, or if an error occurs.

A state is just a string representing the name of the state. A state machine is initialized with a state transition table consisting of a set of allowable transitions, where each transition is a two-element array in which the first element is the from state, and the second element is the to state. This table permits the AbstractStateMachine to determine if a requested transition is valid.

This module is flexible enough to represent both deterministic and non-deterministic finite automata (DFAs and NFAs), but it is fairly new and should be considered experimental.

The key methods in AbstractStateMachine that define this logic of operation are:

check_for_new_state().

Does whatever checking is necessary to determine if a state transition should occur (for example, read a line of input from STDIN). If a transition should occur, a string is returned containing the name of the new state. Otherwise, it returns undef.

This method must be implemented as AbstractStateMachine does not define it (and in fact will throw a NotImplemented exception if you fail to implement it).

change_state( new_state )

Causes the machine to change its state to the state specified in the argument. change_state() allows you to mapping a state transition to a particular handler method that does whatever processing is needed to deal with the state transition.

run()

This method keeps calling check_for_new_state() and if that method returns a defined value (the name of the state to change to), it then calls change_state( $state ), where $state is the value returned by check_for_new_state().

Before calling check_for_new_state(), the run() method checks the current state of the machine and exits the loop if the current state ever becomes $PAUSE_STATE, $ERROR_STATE, or $FINAL_STATE.

append_input_cache( data )

Adds data to a buffer for processing at the next state transition. check_for_new_state() should call append_input_cache() passing it any data it receives while checking for a new state that should be processed later.

get_input_cache()

Retrieves the data stored by calling append_input_cache(). change_state() should call get_input_cache() to obtain the data to be processed for the current transition.

This object defines an abstract class, meaning that some but not all methods have been implemented. Subclasses must define the methods not implemented here. These include at a minimum:

check_for_new_state()
change_state()

A default simple implementation of change_state() is provided, but subclasses of AbstractStateMachine most likely will want to override this method to do something useful according to the particular state change.

If your state machine needs to cache input while processing, you will also need to provide implementations of these methods (which are no-op in AbstractStateMachine):

append_input_cache
get_input_cache
clear_input_cache

There are some other nuances provided by AbstractStateMachine, such as the ability to pause() and resume() the running of the machine.

EXAMPLES

To get a feel for how to use this, have look at scripts in the examples/state-machine directory of the Bioperl distribution. Also have a look at Bio::Tools::StateMachine::IOStateMachine which provides a Bio::Root::IO-based implementation of AbstractStateMachine. Bio::SearchIO::psiblast subclasses IOStateMachine.

FEEDBACK

Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated.

bioperl-l@bioperl.org              - General discussion
http://bio.perl.org/MailList.html  - About the mailing lists

Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via email or the web:

bioperl-bugs@bio.perl.org                   
http://bugzilla.bioperl.org/

AUTHOR

Steve Chervitz, <sac@bioperl.org>

See the FEEDBACK section for where to send bug reports and comments.

ACKNOWLEDGEMENTS

I would like to acknowledge my colleagues at Affymetrix for useful feedback.

COPYRIGHT

Copyright (c) 2001 Steve Chervitz. All Rights Reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DISCLAIMER

This software is provided "as is" without warranty of any kind.

APPENDIX

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

running

The machine is either running or not running. Once the machine has stopped running, it cannot be re-started. Use pause() to temporarily halt a machine without exiting the run state.

transition_table

 Arg      : n/a
 Returns  : An array of array references to two-element arrays.
            Each array ref defines a single transition where
            the first element is the name of the "from" state and
            the second element is the name of the "to" state.

 Example  : $sm->transition_table( [ $INITIAL_STATE, 'State1'],
				   [ 'State1', 'State2' ],
				   [ 'State2', 'State3' ],
				   [ 'State3', $FINAL_STATE]
				 );

add_transition

Arg      : Two string arguments where:
           First string = name of the "from" state.
           Second string = name of the "to" state.
Throws   : A Bio::Root::BadParameter exception if two arguments
           are not provided.

change_state

Purpose  : To cause the machine to change its state.
Argument : A String containing the name of the the new state.
Returns  : n/a
Throws   : A Bio::Tools::StateMachine::StateException exception if the
           state transition cannot be carried out.

This is a default implementation that simply validates the state change (by calling validate_transition) and then calls finalize_state_change() if the transition is valid.

Subclasses of AbstractStateMachine most likely will want to override this method to do something useful according to the particular state change.

get_transitions_from

Purpose  : Returns a list array references that have the indicated state
           in their 'from' slot.

validate_transition

Purpose  : Determines if the desired state change is defined within 
           the set of registered transitions for this StateMachine.
Arg      : Two required arguments:
           [0] string defining the name of the "from" state (case sensitive)
           [1] string defining the name of the "to" state (case sensitive)
Returns  : True if the transition is valid.
           If not valid, throws an exception.
Throws   : A Bio::Tools::StateMachine::StateException if the desired 
           transition does not exist with the registered transitions
           for this machine.
Throws   : A Bio::Root::BadParameter if insufficient arguments are given.

check_for_new_state

Purpose : To do whatever checking is necessary to determine if 
           a state transition should occur. 
Argument : Any necessary data required to determine if the state 
           machine should change to a new state.
Returns  : A string containing the name of the new state if the 
           state machine should change to a new state. 
           Otherwise returns undef.

This is a virtual method and must be implemented by a subclass to do whatever checking is necessary to determine if a state transition should occur. If not implemented, calling this method will result in a Bio::Root::NotImplemented exception.

finalize_state_change

Purpose  : Performs routine operations to finish changing state.
           This method should be called at the end of change_state().
Usage    : finalize_state_change( $new_state, $clear_input_cache );
Argument : $new_state = the name of the state to change to.
           $clear_input_cache = boolean whether or not to zap whatever 
                                was in the input cache. Depends on 
                                the logic of your state machine.