Skip to main content

Running Applications on C0 and C0 Pro Cores

Once you have successfully authenticated yourself and obtained an access token (see Authentication), you can use it to run applications on the Signaloid Cloud Compute Engine via the API. The base URL for the Signaloid Cloud Compute Engine API is api.signaloid.io.

Types of applications/tasks​

On the Signaloid Cloud Compute Engine you can run:

  1. Source Code applications: Applications with a single source file which is treated as a string.
  2. Repository applications: Applications that are hosted in a GitHub repository.

Signaloid Cloud Compute Engine API provides functionality for easily running any type of application through a single API endpoint.

Language support​

Currently, the Signaloid Cloud Compute Engine supports running applications written in C, C++, and FORTRAN. In future releases of the Cloud Compute Engine we will add support for other programming languages.

Application Execution Flow​

Running an application via the API is a five-step process:

  1. Setting up a task request object with the application details
  2. Submitting the task request to /tasks
  3. Retrieving the status of the task from /tasks/{task_id}
  4. Retrieving the results of the task from /tasks/{task_id}/outputs
  5. Post-processing the results of the task

Task request object​

The task request object is a JSON object that contains the details of the application that you want to run.

Source Code task request object​

The code below shows a Typescript type definition for the Source Code task request object.

type SourceCodeTaskRequest = {
  Type: "SourceCode";
  SourceCode: {
    Object: "SourceCode";
    Code: string;
    Arguments: string;
    Language: "C" | "C++" | "Fortran";
  };
  Overrides?: {
    Core?: Core | string;
    DataSources?: DataSource[];
    TraceVariables?: TraceVariable[];
  };
};

For Source Code tasks, the Code field should contain the source code of the application as a string. The Arguments field contains the command line arguments that will be passed to the application when it is executed. The Language field specifies the programming language of the application. For Source Code tasks, the Overrides key can be used to specify the execution core details, the data source mount configuration, and the trace variable configurations.

Repository task request object​

The code below show a Typescript type definition for the Repository task request object.

type RepositoryTaskRequest = {
  Type: "Repository";
  Repository: string;
  Overrides?: {
    Arguments?: string;
    BuildDirectory?: string;
    Core?: Core | string;
    DataSources?: DataSource[];
    TraceVariables?: TraceVariable[];
  };
};

For Repository tasks, the Repository field should contain the Repository ID of the application repository. This can be obtained by using the /respositories API endpoint to connect a Github repository to your account. The Overrides key can be used to override the repository configuration of the repository for a specific task (e.g., if you want to pass different command line arguments or change the build directory).

The Task object​

Once the task request has been prepared, you should make a POST to the /tasks endpoint along with the task request object. If the task is valid, the API will enqueue the task, to be run on the Signaloid Cloud Compute Engine, and return a Task object. The Task object contains the details of the task that you submitted to the API as well as the current status of the task. The Task object has the following structure:

type Task = {
  Object: "Task";
  TaskID: string;
  Owner: string;
  Application: PipelineApplication | RepositoryApplication | SourceCodeApplication; // The application that was submitted to the API
  Status: "Accepted" | "Initialising" | "Building" | "In Progress" | "Completed" | "Cancelled" | "Stopped";
  StatusTransitions: TaskStatusTransition[];
  Stats?: TaskStatistics; /* Statistics about the execution of the task (e.g., processor time) */;
  StartedAt: number /* The time the Task.Status becomes "In Progress" */;
  UpdatedAt: number;
  CreatedAt: number /* The time the Task.Status becomes "Accepted" */;
  FinishedAt: number /* The time the Task.Status becomes "Completed", "Cancelled", or "Stopped" */;
};

Please refer to the reference for the GetTaskByID endpoint for more details on the Task object. The TaskID field of the Task object can be used to query the status of the task and retrieve the results of the task.

Fetching Task Results​

Once the task has completed executing (either successfully or unsuccessfully), you can retrieve the results of the task from the /tasks/{task_id}/outputs endpoint. This endpoint will return a list of URLs to files containing the task output separated into the different output streams; stdout, stderr, and build. The stdout and stderr streams contain the standard output and standard error streams of the application. The build stream contains the build output of the application. The stdout and stderr streams will not be available for tasks that failed to build. The response from the /tasks/{task_id}/outputs endpoint has the following structure:

{
  "Stdout": "string",
  "Stderr": "string",
  "Build": "string",
  "StdoutChunks": ["string"]
}

Please refer to the reference for the Get Task Outputs endpoint for more details on retrieving task outputs.

When running a Task on the Reference microarchitecture, any traced variable value the running program prints to the stdout and stderr streams will have a <ValueID> tag associated with it. When running on uncertainty-tracking C0 cores the values the program prints are Ux Strings. These ValueID values are useful together with the TaskID of the task in order to create plots and generate samples. To plot the distribution of the corresponding variable use the /plot API endpoint. To generate samples use the /samples API endpoint. Please refer to the API reference for the /plot and /samples API endpoints for more details.