# ``twisted`.`internet`.`task`.`CooperativeTask``

class documentation

`class CooperativeTask: (source)`

View In Hierarchy

A `CooperativeTask` is a task object inside a `Cooperator`, which can be paused, resumed, and stopped. It can also have its completion (or termination) monitored.

See Also
`Cooperator.cooperate`

Method | `__init__` | A private constructor: to create a new `CooperativeTask`, see `Cooperator.cooperate`.
Method | `pause` | No summary
Method | `resume` | Resume processing of a paused `CooperativeTask`.
Method | `stop` | Stop further processing of this task.
Method | `whenDone` | Get a `Deferred` notification of when this task is complete.
Method | `_checkFinish` | If this task has been stopped, raise the appropriate subclass of `TaskFinished`.
Method | `_completeWith` |
Method | `_oneWorkUnit` | Perform one unit of work for this task, retrieving one item from its iterator, stopping if there are no further items in the iterator, and pausing if the result was a `Deferred`.
Instance Variable | `_completionResult` | Undocumented
Instance Variable | `_completionState` | The completion-state of this `CooperativeTask`. `None` if the task is not yet completed, an instance of `TaskStopped` if `stop` was called to stop this task early, of `TaskFailed` if the application code in the iterator raised an exception which caused it to terminate, and of `TaskDone` if it terminated normally via raising `StopIteration`.
Instance Variable | `_cooperator` | the `Cooperator` that this `CooperativeTask` participates in, which is used to re-insert it upon resume.
Instance Variable | `_deferreds` | the list of `Deferred`s to fire when this task completes, fails, or finishes.
Instance Variable | `_iterator` | the iterator to iterate when this `CooperativeTask` is asked to do work.
Instance Variable | `_pauseCount` | the number of times that this `CooperativeTask` has been paused; if 0, it is running.

def __init__(self, iterator, cooperator): (source)
A private constructor: to create a new `CooperativeTask`, see `Cooperator.cooperate`.

Parameters
iterator:`Iterator[_TaskResultT]` | Undocumented
cooperator:`Cooperator` | Undocumented

def pause(self): (source)
Pause this `CooperativeTask`. Stop doing work until `CooperativeTask.resume` is called. If `pause` is called more than once, `resume` must be called an equal number of times to resume this task.

Raises
`TaskFinished` | if this task has already finished or completed.

def resume(self): (source)
Resume processing of a paused `CooperativeTask`.

Raises
`NotPaused` | if this `CooperativeTask` is not paused.

def stop(self): (source)
Stop further processing of this task.

Raises
`TaskFinished` | if this `CooperativeTask` has previously completed, via `stop`, completion, or failure.

def whenDone(self): (source)
Get a `Deferred` notification of when this task is complete.

Returns
`Deferred` | a `Deferred` that fires with the `iterator` that this `CooperativeTask` was created with when the iterator has been exhausted (i.e. its `next` method has raised `StopIteration`), or fails with the exception raised by `next` if it raises some other exception.

def _checkFinish(self): (source)
If this task has been stopped, raise the appropriate subclass of `TaskFinished`.
def _completeWith(self, completionState, deferredResult): (source)

Parameters
completionState:`SchedulerError` | a `SchedulerError` exception or a subclass thereof, indicating what exception should be raised when subsequent operations are performed.
deferredResult:`Union[Iterator[_TaskResultT], Failure]` | the result to fire all the deferreds with.

def _oneWorkUnit(self): (source)
Perform one unit of work for this task, retrieving one item from its iterator, stopping if there are no further items in the iterator, and pausing if the result was a `Deferred`.
_completionResult = (source)

Undocumented

_completionState = (source)
The completion-state of this `CooperativeTask`. `None` if the task is not yet completed, an instance of `TaskStopped` if `stop` was called to stop this task early, of `TaskFailed` if the application code in the iterator raised an exception which caused it to terminate, and of `TaskDone` if it terminated normally via raising `StopIteration`.
_cooperator = (source)
the `Cooperator` that this `CooperativeTask` participates in, which is used to re-insert it upon resume.
_deferreds: `List[Deferred[Iterator[_TaskResultT]]]` = (source)
the list of `Deferred`s to fire when this task completes, fails, or finishes.
_iterator = (source)
the iterator to iterate when this `CooperativeTask` is asked to do work.
_pauseCount: `int` = (source)
the number of times that this `CooperativeTask` has been paused; if 0, it is running.