BeeCluster API
BeeCluster API Overview
BeeCluster API allows developers to describe their application logic through a dynamic task graph (DTG) based imperative programming model. It also allows developers to explicitly define the precise binding relationship between virtual drones and physical drones, e.g., some actions must be done on one physical drone sequentially, while some other actions can be done with multiple physical drones in parallel.
Building Blocks
BeeCluster API has two basic building blocks - actions and tasks.
Action. An action is a basic drone operation such as taking a photo or flying to a location.
Task. A task contains an ordered sequence of actions and maintains the context of a virtual drone; when there are two consecutive actions such that action-1 is flying to location A, and action-2 is taking a photo, the BeeCluster runtime will update the location of the virtual drone after action 1 and interpret the second action as taking a photo at location A.
Basic API
We show the basic BeeCluster API in the following table.
| API Name | Description |
|---|---|
| h = act(args) | Execute the action defined by args on a drone. Return an action handler h. This function call is non-blocking but in-order - an action is executed when all its predeceased actions in the current thread have been completed. |
| h = newTask(flags, func, args) | Create a new task (a new thread) with the entry point as function func with arguments args. The flags parameter defines the binding relationship of the task. This function is non-blocking; it returns a task handler h immediately after the function call. |
| result=h.value | Retrieve the result from a handler h. This operation is blocking. |
| cancelTasks(taskHandlers) | Cancel the tasks specified by the taskHandlers. |
note
The API in the above table is the high-level definition of BeeCluster API.
Tasks run as Threads
Developers use newTask() to create new tasks. Task creation is non-blocking; the blocking (synchronization) only happens when the execution result of a task is required by another statement, i.e., a statement that depends on the execution result of the task. In BeeCluster, each task corresponds to an independent thread, and the thread can be executed in parallel with other threads when there are available drones. The task primitive allows developers to describe independent action sequences, e.g., that the application needs to take photos at a set of locations, but the order of execution does not matter. In this case, traveling to a location and taking a photo would be a single task, and there would be one task for each location in the set.
Binding Relationships
The developers can define the binding relationship of the actions within a task. The binding relationship provide a way to control the mapping of virtual drones to the physical drones. BeeCluster supports four binding relationships defined by the combinations of two flags.
SameDrone Flag. When the SameDrone flag is set to be True, all the actions within the task need to be done on one physical drone. Otherwise, the actions within the task can be mapped to different physical drones.
Interruptible Flag. When the Interruptible flag is set to be False , all the actions within the task need to be done one after another, without a large gap in time (best-effort). Otherwise, there could be large gap in time, e.g., 5 minutes, between two consecutive actions.