Docs

Torch Object Storage

FSX

How FSX works

This topic explains the semantics of read and write operations, objects and directories, and data caching in FSX, helping you use FSX more effectively.

Read and write

Applications can access entire objects within a TOS bucket or read specific portions of data from specified offsets via FSX. For sequential reading of large objects, FSX can automatically prefetch data from TOS to improve bandwidth throughput. By default, FSX neither downloads objects to the local directory nor consumes local storage space. Data is only cached in the read cache directory after the read cache mount parameters are configured.

For write operations, applications must start writing from the beginning of an object. Only sequential writes are supported. Random writes are not supported. By default, FSX writes data to a local temporary directory. You can specify a directory using the temp_dir parameter when mounting a bucket. This directory will be generated under /tmp/. If performance is important to you, specify tmpfs as the directory for temporary files. During a multipart upload, FSX asynchronously uploads the data to the TOS server after a part is filled to the part_size and optimizes write throughput through concurrent uploads.

An object only becomes visible to other clients after the application that opened it closes it and no further writes are permitted. When overwriting an existing object, the application must set the O_TRUNC flag when opening the object to indicate that it needs to be truncated.

warning

Since write operations initially save data to a temporary directory, make sure the directory has enough space for the data being written. The temporary directory must have at least 10,240 * part_size bytes of space. For example, with a default part_size of 8 M, 80 GiB of space is required.

Listing objects or directories

Because list operations usually take a long time to finish, FSX adds a prefetch cache to minimize requests to the TOS server. This improves list performance and lowers costs associated with list requests.

Objects and directories

Directories are an essential part of file systems. FSX interprets "/" as a directory separator in object names, allowing it to automatically infer the directory structure of TOS buckets. For example, if a bucket contains an object named "dir1/dir2/file", then "dir1/" and "dir2/" are treated as directories and "file" is treated as an object. The hierarchy would be dir1/, dir1/dir2/, and dir1/dir2/file.

If a directory and an object have the same name, the directory takes precedence and the object is ignored. For example, if objects "a/b" and "a/b/c" coexist, the "b" in "a/b" is treated as an object, whereas the "b" in "a/b/c" is treated as a directory. During mapping, the object "a/b" is ignored. If the object "a/b/c" is deleted later, there will be no naming conflict with "b," and the object "a/b" will become visible again.

Data caching

FSX provides local data caching to improve performance when specific objects containing small amounts of data are accessed frequently. Enabling data caching can reduce the number of requests to TOS for the same data from the same compute instance, which lowers costs and potentially improves read performance.

warning

Using data caching can affect the consistency and validity of the data, which could result in users accessing outdated information. Therefore, it is not recommended for scenarios that require high data timeliness and consistency.

Caching data for one-time reads is also not recommended because it does not improve performance or reduce costs.

After enabling data caching, you must specify the cache directory and cache size. FSX will then create a new subdirectory within the specified cache directory when the bucket is mounted. FSX will also delete any objects or directories within this subdirectory during mount and unmount operations. Once the cached data reaches the set size limit, FSX proactively removes the least recently used data blocks from the cache directory.

Last updated: 2025.11.25 14:05:57