job.fileStore API¶
The AbstractFileStore is an abstraction of a Toil run’s shared storage.
-
class
toil.fileStores.abstractFileStore.AbstractFileStore(jobStore, jobGraph, localTempDir, waitForPreviousCommit)[source]¶ Interface used to allow user code run by Toil to read and write files.
Also provides the interface to other Toil facilities used by user code, including:
- normal (non-real-time) logging
- finding the correct temporary directory for scratch work
- importing and exporting files into and out of the workflow
Stores user files in the jobStore, but keeps them separate from actual jobs.
May implement caching.
Passed as argument to the
toil.job.Job.run()method.Access to files is only permitted inside the context manager provided by
toil.fileStores.abstractFileStore.AbstractFileStore.open().Also responsible for committing completed jobs back to the job store with an update operation, and allowing that commit operation to be waited for.
-
__init__(jobStore, jobGraph, localTempDir, waitForPreviousCommit)[source]¶ Create a new file store object.
Parameters: - jobStore (toil.jobStores.abstractJobStore.AbstractJobStore) – the job store in use for the current Toil run.
- jobGraph (toil.jobGraph.JobGraph) – the job graph object for the currently running job.
- localTempDir (str) – the per-worker local temporary directory, under which per-job directories will be created. Assumed to be inside the workflow directory, which is assumed to be inside the work directory.
- waitForPreviousCommit – the waitForCommit method of the previous job’s file store, when jobs are running in sequence on the same worker. Used to prevent this file store’s startCommit and the previous job’s startCommit methods from running at the same time and racing. If they did race, it might be possible for the later job to be fully marked as completed in the job store before the eralier job was.
-
static
shutdownFileStore(workflowDir, workflowID)[source]¶ Carry out any necessary filestore-specific cleanup.
This is a destructive operation and it is important to ensure that there are no other running processes on the system that are modifying or using the file store for this workflow.
This is the intended to be the last call to the file store in a Toil run, called by the batch system cleanup function upon batch system shutdown.
Parameters:
-
open(job)[source]¶ The context manager used to conduct tasks prior-to, and after a job has been run. File operations are only permitted inside the context manager.
Parameters: job (toil.job.Job) – The job instance of the toil job to run.
-
getLocalTempDir()[source]¶ Get a new local temporary directory in which to write files that persist for the duration of the job.
Returns: The absolute path to a new local temporary directory. This directory will exist for the duration of the job only, and is guaranteed to be deleted once the job terminates, removing all files it contains recursively. Return type: str
-
getLocalTempFile()[source]¶ Get a new local temporary file that will persist for the duration of the job.
Returns: The absolute path to a local temporary file. This file will exist for the duration of the job only, and is guaranteed to be deleted once the job terminates. Return type: str
-
getLocalTempFileName()[source]¶ Get a valid name for a new local file. Don’t actually create a file at the path.
Returns: Path to valid file Return type: str
-
writeGlobalFile(localFileName, cleanup=False)[source]¶ Takes a file (as a path) and uploads it to the job store.
Parameters: - localFileName (string) – The path to the local file to upload.
- cleanup (bool) – if True then the copy of the global file will be deleted once the job and all its successors have completed running. If not the global file must be deleted manually.
Returns: an ID that can be used to retrieve the file.
Return type:
-
writeGlobalFileStream(cleanup=False)[source]¶ Similar to writeGlobalFile, but allows the writing of a stream to the job store. The yielded file handle does not need to and should not be closed explicitly.
Parameters: cleanup (bool) – is as in toil.fileStores.abstractFileStore.AbstractFileStore.writeGlobalFile().Returns: A context manager yielding a tuple of 1) a file handle which can be written to and 2) the toil.fileStores.FileID of the resulting file in the job store.
-
readGlobalFile(fileStoreID, userPath=None, cache=True, mutable=False, symlink=False)[source]¶ Makes the file associated with fileStoreID available locally. If mutable is True, then a copy of the file will be created locally so that the original is not modified and does not change the file for other jobs. If mutable is False, then a link can be created to the file, saving disk resources.
If a user path is specified, it is used as the destination. If a user path isn’t specified, the file is stored in the local temp directory with an encoded name.
The destination file must not be deleted by the user; it can only be deleted through deleteLocalFile.
Parameters: - or str fileStoreID (toil.fileStores.FileID) – job store id for the file
- userPath (string) – a path to the name of file to which the global file will be copied or hard-linked (see below).
- cache (bool) – Described in
toil.fileStores.CachingFileStore.readGlobalFile() - mutable (bool) – Described in
toil.fileStores.CachingFileStore.readGlobalFile()
Returns: An absolute path to a local, temporary copy of the file keyed by fileStoreID.
Return type:
-
readGlobalFileStream(fileStoreID)[source]¶ Similar to readGlobalFile, but allows a stream to be read from the job store. The yielded file handle does not need to and should not be closed explicitly.
Returns: a context manager yielding a file handle which can be read from.
-
getGlobalFileSize(fileStoreID)[source]¶ Get the size of the file pointed to by the given ID, in bytes.
If a FileID or something else with a non-None ‘size’ field, gets that.
Otherwise, asks the job store to poll the file’s size.
Note that the job store may overestimate the file’s size, for example if it is encrypted and had to be augmented with an IV or other encryption framing.
Parameters: or str fileStoreID (toil.fileStores.FileID) – File ID for the file Returns: File’s size in bytes, as stored in the job store Return type: int
-
deleteLocalFile(fileStoreID)[source]¶ Deletes local copies of files associated with the provided job store ID.
The files deleted are all those previously read from this file ID via readGlobalFile by the current job into the job’s file-store-provided temp directory, plus the file that was written to create the given file ID, if it was written by the current job from the job’s file-store-provided temp directory.
Parameters: or str fileStoreID (toil.fileStores.FileID) – File Store ID of the file to be deleted.
-
deleteGlobalFile(fileStoreID)[source]¶ Deletes local files with the provided job store ID and then permanently deletes them from the job store. To ensure that the job can be restarted if necessary, the delete will not happen until after the job’s run method has completed.
Parameters: or str fileStoreID (toil.fileStores.FileID) – the File Store ID of the file to be deleted.
-
logToMaster(text, level=20)[source]¶ Send a logging message to the leader. The message will also be logged by the worker at the same level.
Parameters: - text – The string to log.
- level (int) – The logging level.
-
startCommit(jobState=False)[source]¶ Update the status of the job on the disk.
May start an asynchronous process. Call waitForCommit() to wait on that process.
Parameters: jobState (bool) – If True, commit the state of the FileStore’s job, and file deletes. Otherwise, commit only file creates/updates.
-
waitForCommit()[source]¶ Blocks while startCommit is running. This function is called by this job’s successor to ensure that it does not begin modifying the job store until after this job has finished doing so.
Might be called when startCommit is never called on a particular instance, in which case it does not block.
Returns: Always returns True Return type: bool
-
classmethod
shutdown(dir_)[source]¶ Shutdown the filestore on this node.
This is intended to be called on batch system shutdown.
Parameters: dir – The implementation-specific directory containing the required information for shutting down the file store and removing all its state and all job local temp directories from the node.
-
class
toil.fileStores.FileID(fileStoreID, size)[source]¶ A small wrapper around Python’s builtin string class. It is used to represent a file’s ID in the file store, and has a size attribute that is the file’s size in bytes. This object is returned by importFile and writeGlobalFile.
Calls into the file store can use bare strings; size will be queried from the job store if unavailable in the ID.
