A Worker manages an external R session and completes tasks.
Details
The Worker class interacts with an external R session, and possesses
methods that allow it to work with Task objects. At its core, the
class is a thin wrapper around a callr::r_session object, and in fact
the session object itself can be obtained by calling the
get_worker_session() method. In most cases this shouldn't be necessary
however, because Worker objects are typically created as part of a
WorkerPool that is managed by a Queue, and those higher level structures
use the methods exposed by the Worker object.
Methods
Method get_worker_state()
Retrieve the worker state.
Returns
A string specifying the current state of the R session. Possible values are:
"starting": the R session is starting up."idle": the R session is ready to compute."busy": the R session is computing."finished": the R session has terminated.
Importantly, note that a task
function that is still running and a task function that is essentially
finished and waiting to return will both return "busy". To distinguish
between these two cases you need to use the poll_process() method of
a callr::rsession, as returned by get_worker_session().
Method get_worker_runtime()
Return the total length of time the worker session
has been running, and the length of the time that the current task
has been running. If the session is finished both values are NA.
If the session is idle (no task running) the total session time will
return a value but the current task time will be NA.
Method get_worker_session()
Retrieve the R session associated with a Worker
Returns
An R session object, see callr::r_session
Method try_assign()
Attempt to assign a task to this worker. This method checks
that the task and the worker are both in an appropriate state. If they
are, both objects register their connection to the other. This method is
intended to be called by a WorkerPool or a Queue.
Method try_start()
Attempt to start the task. This method checks to see if the
that worker has an assigned task, and if so starts it running within the
R session. It also registers the change of status within the Task
object itself. This method is intended to be called by a WorkerPool
or a Queue.
Method try_finish()
Attempt to finish a running task politely. This method checks
to see if the worker has a running task, and if so polls the R session to
determine if the R process claims to be ready to return. If there is a
ready-to-return task the results are read from the R process and returned
to the Task object. The task status is updated, and then unassigned
from the Worker. This method is intended to be called by a WorkerPool
or a Queue.
Method shutdown_worker()
Attempt to shut down the R session gracefully, after making
an attempt to salvage any task that the worker believes it has been
assigned. The salvage operation depends on the state of the task. If the
Task has been assigned but not started, the Worker will return it
to a "waiting" state in the hope that the Queue will assign it to
another worker later, and unassign it. If the Task is running, the
Worker will attempt to read from the R session and then register the
Task as "done" regardless of the outcome. (The reason for this is to
ensure that tasks that crash or freeze the R session don't get returned
to the Queue).