Description

This is a object module used by Stem Cells and objects to detect when a set of asynchronous events have finished. It is constructed by an owner object which then stores it in itselt. Gather objects are initialized with a set of keys to be gathered. When the owner object is notified of an event, it calls the gathered method of the gather object with a list of keys. When all of the keys are gathered, a callback is made to the owner object. An optional timeout is available which will also generate a callback if the keys are not gathered in time.

Synopsis

	use Stem::Gather ;

        # $self is the owner object that has already been created

	my $gather = Stem::Gather->new(
		'object'	=> $self,
		'keys'		=> [qw( msg1 msg2 )]
	) ;

	$self->{'gather'} = $gather ;

	sub msg1_in {

		my( $self ) = @_ ;
		$self->{'gather'}->gathered( 'msg1' ) ;
	}

	sub msg2_in {

		my( $self ) = @_ ;
		$self->{'gather'}->gathered( 'msg2' ) ;
	}

	sub gather_done {

		my( $self ) = @_ ;

		print "we have gathered\n" ;
	}

Constructor Attributes for Class Stem::Gather

• Attribute - object

  Description: This is the owner object which has the methods that get called when Stem::Gather has either finished gathering all of the keys or it has timed out.

  Its type is: object

  It is required.

• Attribute - keys

  Description: This is the list of keys to gather.

  Its type is: list

  It is required.

• Attribute - gathered_method

  Description: This method is called in the owner object when all of the keys are gathered.

  It defaults to: gather_done

• Attribute - no_start

  Description: If set, then do not start the gather object upon creation. A call to the restart must be made. This only meaningful if this gather has a timeout set.

  Its type is: boolean

• Attribute - timeout

  Description: This is an optional timeout period (in seconds) waiting for the gather to be completed

• Attribute - timeout_method

  Description: This method is called in the owner object if the gather timed out before all keys were gathered.

  It defaults to: gather_timeout

Method new

This is the constructor method for Stem::Gather. It uses the standard Stem key/value API with the

Method restart

This method is called to start up the gather object when it has already gathered all the keys, it has timed out or it was never started (the no_start attribute was enabled). It takes no arguments.

Method add_keys

This method is passed a list of keys which will be added to the list to be watched for by the Stem::Gather object. The new keys are not looked for until a call to the restart method is made.

Method gathered

This method is called with a list of keys that are gathered. The keys that haven't been gathered before are marked as gathered. If there are no more keys to be gathered, the method in the gathered_method attribute is called in the owner object. You have to call the restart method on this gather object to use it again.You can pass this methods keys that have been gathered or are not even in the list to be gathered and they are ignored.

Method

This method must be called if the owner object is being shut down or destroyed. It will cancel any pending timeout and break the link back to the owner object. The owner object can then be destroyed without leaking memory.