Application task queue (IRPCApplicationTaskQueue)

View as Markdown

Persistent task queues and broadcast messages that vault applications use to share background work between the server instances of a vault.

This interface provides access to vault specific task queue for adding and managing the tasks.

Overview

This is the server side of the task queue API that vault applications use through the M-Files API (Vault.ApplicationTaskOperations). A vault application opens named queues, adds tasks with an opaque payload, and its instances on every server of the vault reserve, process and update them. Queues also carry broadcast messages that every consumer reads.

Who should call it. Vault applications, through the M-Files API. An external application normally should not: the queues belong to the vault applications that open them, and reserving or updating their tasks takes work away from those applications. Use it only for queues that your own code owns, or read-only for diagnostics (GetTaskQueues, GetTaskIdentifiersFromQueue, GetApplicationTasks).

Rights. Every method needs a vault session of a user with an account in the vault and the vault right change_full_control_role, which only users with full control of the vault have; a normal user gets "Access denied.". The vault's internal queues, such as m-files.server.core.broadcast, are refused with "Access denied." by the methods that open, add to, reserve from, broadcast to or destroy a queue, but they are listed by GetTaskQueues.

Task life cycle (ApplicationTaskState):

1. OpenTaskQueue creates the queue if it does not exist. Call it before adding or reserving.
2. AddTask or AddScheduledTask adds a task in state APPLICATION_TASK_STATE_WAITING.
3. ReserveTasksForProcessing moves a waiting task to APPLICATION_TASK_STATE_IN_PROGRESS and returns it to one caller.
4. UpdateTask reports progress and finally sets COMPLETED, FAILED or CANCELED. An in-progress task that is not updated within its restore timeout goes back to waiting and can be reserved again.

The server cleans up by itself: completed tasks are deleted; failed and cancelled tasks and broadcast messages after a day; and queues that have not been used for seven days, together with their tasks.

Methods