ITaskManager Interface

A distributed data structure that tracks queues of clients that want to exclusively run a task.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/task-manager/legacy.

For more information about our API support guarantees, see here.

Signature

export interface ITaskManager extends ISharedObject<ITaskManagerEvents>

Extends: ISharedObject<ITaskManagerEvents>

Usage

Example 1

Creation

To create a ITaskManager, call the static create method:

const taskManager = TaskManager.create(this.runtime, id);

Example 2

Usage

To volunteer for a task, use the volunteerForTask(taskId) method. This returns a Promise that will resolve once the client has acquired exclusive rights to run the task, or reject if the client is removed from the queue without acquiring the rights.

taskManager.volunteerForTask("NameOfTask")
    .then(() => { doTheTask(); })
    .catch((err) => { console.error(err); });

Alternatively, you can indefinitely volunteer for a task with the synchronous subscribeToTask(taskId) method. This method does not return a value, therefore you need to rely on eventing to know when you have acquired the rights to run the task (see below).

taskManager.subscribeToTask("NameOfTask");

To check if the local client is currently subscribed to a task, use the subscribed(taskId) method.

if (taskManager.subscribed("NameOfTask")) {
    console.log("This client is currently subscribed to the task.");
}

To release the rights to the task, use the abandon(taskId) method. The next client in the queue will then get the rights to run the task.

taskManager.abandon("NameOfTask");

To inspect your state in the queue, you can use the queued(taskId) and assigned(taskId) methods.

if (taskManager.queued("NameOfTask")) {
    console.log("This client is somewhere in the queue, potentially even having the task assignment.");
}
if (taskManager.assigned("NameOfTask")) {
    console.log("This client currently has the rights to run the task");
}

To signal to other connected clients that a task is completed, use the complete(taskId) method. This will release all clients from the queue and emit the "completed" event.

taskManager.complete("NameOfTask");

Example 3

Eventing

ITaskManager will emit events when a task is assigned to the client, when the task assignment is lost, and when a task was completed by another client.

taskManager.on("assigned", (taskId: string) => {
    console.log(`Client was assigned task: ${taskId}`);
});
taskManager.on("lost", (taskId: string) => {
    console.log(`Client released task: ${taskId}`);
});
taskManager.on("completed", (taskId: string) => {
    console.log(`Another client completed task: ${taskId}`);
});

These can be useful if the logic to volunteer for a task is separated from the logic to perform the task, such as when using subscribeToTask(taskId).

See ITaskManagerEvents for more details.

Methods

Method	Alerts	Return Type	Description
abandon(taskId)	Alpha	void	Exit the queue, releasing the task if currently assigned.
assigned(taskId)	Alpha	boolean	Check whether this client is the current assignee for the task and there is no outstanding abandon op that would abandon the assignment.
canVolunteer()	Alpha	boolean	Check whether this client can currently volunteer for a task.
complete(taskId)	Alpha	void	Marks a task as completed and releases all clients from its queue.
queued(taskId)	Alpha	boolean	Check whether this client is either the current assignee, in queue, or we expect they will be in queue after outstanding ops have been ack'd.
subscribed(taskId)	Alpha	boolean	Check whether this client is currently subscribed to the task.
subscribeToTask(taskId)	Alpha	void	Continuously volunteer for the task. Watch the "assigned" event to determine if the task is assigned. The local client will automatically re-enter the queue if it disconnects.
volunteerForTask(taskId)	Alpha	Promise<boolean>	Volunteer for the task. Returns a promise that resolves true if the task is assigned to the local client and false if the task was completed by another client. It rejects if the local client abandoned the task or disconnected while in queue.

Method Details

abandon

Exit the queue, releasing the task if currently assigned.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/task-manager/alpha.

For more information about our API support guarantees, see here.

Signature

abandon(taskId: string): void;

Parameters

Parameter	Type	Description
taskId	string	Identifier for the task

assigned

Check whether this client is the current assignee for the task and there is no outstanding abandon op that would abandon the assignment.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/task-manager/alpha.

For more information about our API support guarantees, see here.

Signature

assigned(taskId: string): boolean;

Parameters

Parameter	Type	Description
taskId	string	Identifier for the task

Returns

Return type: boolean

canVolunteer

Check whether this client can currently volunteer for a task.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/task-manager/alpha.

For more information about our API support guarantees, see here.

Signature

canVolunteer(): boolean;

Returns

Return type: boolean

complete

Marks a task as completed and releases all clients from its queue.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/task-manager/alpha.

For more information about our API support guarantees, see here.

Signature

complete(taskId: string): void;

Parameters

Parameter	Type	Description
taskId	string	Identifier for the task

queued

Check whether this client is either the current assignee, in queue, or we expect they will be in queue after outstanding ops have been ack'd.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/task-manager/alpha.

For more information about our API support guarantees, see here.

Signature

queued(taskId: string): boolean;

Parameters

Parameter	Type	Description
taskId	string	Identifier for the task

Returns

Return type: boolean

subscribed

Check whether this client is currently subscribed to the task.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/task-manager/alpha.

For more information about our API support guarantees, see here.

Signature

subscribed(taskId: string): boolean;

Parameters

Parameter	Type	Description
taskId	string	Identifier for the task

Returns

Return type: boolean

subscribeToTask

Continuously volunteer for the task. Watch the "assigned" event to determine if the task is assigned. The local client will automatically re-enter the queue if it disconnects.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/task-manager/alpha.

For more information about our API support guarantees, see here.

Signature

subscribeToTask(taskId: string): void;

Parameters

Parameter	Type	Description
taskId	string	Identifier for the task

volunteerForTask

Volunteer for the task. Returns a promise that resolves true if the task is assigned to the local client and false if the task was completed by another client. It rejects if the local client abandoned the task or disconnected while in queue.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/task-manager/alpha.

For more information about our API support guarantees, see here.

Signature

volunteerForTask(taskId: string): Promise<boolean>;

Parameters

Parameter	Type	Description
taskId	string	Identifier for the task

Returns

Return type: Promise<boolean>