Disk operations

Most programming languages offer the ability to perform disk operations (e.g., creating files). The Sphere Engine service allows you to perform such operations within an isolated workspace dedicated to a single submission.

Workspace

Regardless of the environment in which the program is executed, disk operations require appropriate permissions. Sphere Engine execution environment provides a dedicated workspace for the submission with appropriate permissions.

The workspace is:

• temporary – the workspace is created at the beginning of processing the submission and destroyed after its completion; it means that the files created during the execution of the submission are no longer available after the submission has been executed,
• isolated – the workspace is not available for other submissions,
• clean at start – the workspace is empty at the start of processing the submission.

The workspace is a directory inside cloud storage. Due to the isolation feature, the access path to the workspace is generated randomly and made available to the submission via the environment variable named $WORKSPACE.

The $WORKSPACE environment variable contains the absolute path to the directory with permissions to perform disk operations. A sample path might look like this: /tmp/52981b4e-f464-4a6e-baa8-976287248de0.

Features of the workspace

The program's permissions inside the workspace allow for:

• manipulating directories,
  • creating,
  • deleting,
  • moving,
  • renaming,
• manipulating files,
  • creating,
  • deleting,
  • moving,
  • reading,
  • modifying name,
  • modifying content,
• manipulating file and directory permissions,
• retrieving information about files and directories (e.g., size).

Submission performing file operations

The following PHP program retrieves the workspace path, creates a directory named test, and then creates a test.txt file inside it.

<?php

// retrieve workspace absolute path from environment variable
$workspacePath = getenv('WORKSPACE');

$testDirectoryPath = $workspacePath . '/test';
$testFilePath = $testDirectoryPath . '/test.txt';

// create a "test" directory
mkdir($testDirectoryPath);

// create a "test.txt" file in the "test" directory
// the content of the file is "test file content"
file_put_contents($testFilePath, 'test file content');

Disk operations in programming problems

The workspace is shared by all components activated to verify the correctness of the submission, i.e.,:

• the user's program (for each test case),
• the test case judge (for each test case),
• the master judge.

Before executing the user's program for the first test case, the workspace is empty (following the clean start property). During subsequent runs of the program or judges (for the next test cases as a part of processing the same submission), the workspace contains all files and directories that have been created during the process.

The test cases are executed successively. The exact order of execution is as follows:

1. user's program (test case #1)
2. test case judge (test case #1)
3. user's program (test case #2)
4. test case judge (test case #2)
   (…)

14. master judge

Allowing for the use of disk operations by the user's program (and judging programs) extends the possibilities offered by programming problems on the Sphere Engine platform.

Thanks to this, it is possible to:

• verify the ability to manipulate files and directories from the level of the program,
• transfer information between test cases,
• create problems that require performing many operations and save their results in separate files,
• create problems in which subsequent test cases require the use of data generated in earlier test cases (see example below).

Example

Consider a problem that requires executing certain operations on data saved in the CSV format. In the first test case, the initial data will be provided and should then be converted to a normalized form (e.g., present all decimal numbers in the data using the "." character to separate the fractional part). The normalized data should be saved in the workspace as a file called data_normalized.csv.

The second test case is based on the file that was created earlier. The purpose of the test case is to filter data according to a certain criterion. The resulting data should also be saved inside the workspace, this time in a file named data_filtered.csv.

The purpose of the last test case is to calculate statistics for the data in the previously created file. The generated statistics should be saved in the workspace in a file named summary.dat.