Padre::Task - Padre Task API 2.0

package Padre::Task;

use 5.008005;
use strict;
use warnings;
use Storable          ();
use Scalar::Util      ();
use Params::Util      ();
use Padre::Current    ();
use Padre::Role::Task ();

our $VERSION    = '0.86';
our $COMPATIBLE = '0.65';

sub new {
	my $class = shift;
	my $self = bless {@_}, $class;

	if ( exists $self->{owner} ) {

		# Check parameters relevant to our optional owner
		if ( exists $self->{on_message} ) {
			my $method = Params::Util::_IDENTIFIER( $self->{on_message} );
			unless ($method) {
				die "Task 'on_message' must be a method name";
			}
			unless ( $self->{owner}->can($method) ) {
				die "The on_message handler '$method' is not implemented";
			}
		}
		if ( exists $self->{on_finish} ) {
			unless ( Params::Util::_IDENTIFIER( $self->{on_finish} ) ) {
				die "Task 'on_finish' must be a method name";
			}
		}
		my $method = $self->on_finish;
		unless ( $self->{owner}->can($method) ) {
			die "Task on_finish '$method' is not implemented";
		}

		# Save the numeric identifier of our owner
		$self->{owner} = $self->{owner}->task_revision;
	}

	return $self;
}

sub handle {
	$_[0]->{handle};
}

sub running {
	defined $_[0]->{handle};
}

sub owner {
	Padre::Role::Task->task_owner( $_[0]->{owner} );
}

sub on_message {
	$_[0]->{on_message};
}

sub on_finish {
	$_[0]->{on_finish} || 'task_finish';
}





######################################################################
# Serialization - Based on Process::Serializable and Process::Storable

# my $string = $task->as_string;
sub as_string {
	Storable::nfreeze( $_[0] );
}

# my $task = Class::Name->from_string($string);
sub from_string {
	my $class = shift;
	my $self  = Storable::thaw( $_[0] );
	unless ( Scalar::Util::blessed($self) eq $class ) {

		# Because this is an internal API we can be brutally
		# unforgiving is we aren't use the right way.
		die("Task unexpectedly did not deserialize as a $class");
	}
	return $self;
}





######################################################################
# Task API - Based on Process.pm

# Send the task to the task manager to be executed
sub schedule {
	Padre::Current->ide->task_manager->schedule(@_);
}

# Called in the parent thread immediately before being passed
# to the worker thread. This method should compensate for
# potential time difference between when C<new> is original
# called, and when the Task is actually run.
# Returns true if the task should continue and be run.
# Returns false if the task is irrelevant and should be aborted.
sub prepare {
	return 1;
}

# Called in the worker thread, and should continue the main body
# of code that needs to run in the background.
# Variables saved to the object in the C<prepare> method will be
# available in the C<run> method.
sub run {
	my $self = shift;

	# If we have an owner, and it has moved on to a different state
	# while we have been waiting to be executed abort the run.
	if ( $self->{owner} ) {
		$self->owner or return 0;
	}

	return 1;
}

# Called in the parent thread immediately after the task has
# completed and been passed back to the parent.
# Variables saved to the object in the C<run> method will be
# available in the C<finish> method.
# The object may be destroyed at any time after this method
# has been completed.
sub finish {
	my $self = shift;

	if ( $self->{owner} ) {
		my $owner = $self->owner or return;
		my $method = $self->on_finish;
		$owner->$method($self);
	}

	return 1;
}





######################################################################
# Birectional Communication

sub cancel {
	return !!( defined $_[0]->{handle} and $_[0]->{handle}->cancel );
}

sub dequeue {
	return unless defined $_[0]->{handle};
	return $_[0]->{handle}->dequeue;
}

sub dequeue_nb {
	return unless defined $_[0]->{handle};
	return $_[0]->{handle}->dequeue_nb;
}

1;