Enum Class StorageMode

java.lang.Object
java.lang.Enum<StorageMode>
com.frostwire.jlibtorrent.StorageMode
All Implemented Interfaces:
Serializable, Comparable<StorageMode>, Constable
public enum StorageMode extends Enum<StorageMode>
Disk storage allocation strategy for torrents.

StorageMode controls how downloaded data is laid out on disk. Different strategies have trade-offs between disk space usage, fragmentation, and I/O performance.

Storage Modes:

SPARSE (Recommended Default): Files are allocated incrementally as pieces arrive. Uses sparse file support on modern filesystems to avoid pre-allocating entire files. This is the default and recommended mode. 

 Advantages:
 - Only uses disk space for downloaded data
 - Works on all filesystems
 - Faster download startup (no allocation delay)
 - Easier to resume on limited storage

 Disadvantages:
 - May cause file fragmentation over time
 - Some filesystems may handle sparse files inefficiently

 Usage: (default, no explicit setting needed)
 AddTorrentParams params = new AddTorrentParams();
 // StorageMode.STORAGE_MODE_SPARSE is default

ALLOCATE (Full Pre-allocation): All disk space for the torrent is allocated upfront using fallocate() or similar OS calls. Files reach their final size immediately, before any data is downloaded. 

 Advantages:
 - Zero fragmentation (optimal disk layout)
 - Faster downloads (no allocation overhead during transfer)
 - Guarantees contiguous storage on most filesystems
 - Better predictable I/O performance

 Disadvantages:
 - Slower download startup (allocate entire torrent first)
 - Fails if insufficient disk space available
 - Wastes space on failed downloads
 - Not suitable for drives with limited space

 When to use:
 - High-performance dedicated seeds/NAS
 - Very large torrents (minimize fragmentation)
 - Drives with plenty of free space

 Usage:
 AddTorrentParams params = new AddTorrentParams();
 params.storageMode(StorageMode.STORAGE_MODE_ALLOCATE);
 sm.download(ti, saveDir, null, null, null, params.flags());

Comparison Table: 

 ┌─────────────────────────────────────────┬────────────┬──────────┐
 │ Characteristic                          │   SPARSE   │ ALLOCATE │
 ├─────────────────────────────────────────┼────────────┼──────────┤
 │ Startup time                            │ Fast       │ Slow*    │
 │ Disk space usage                        │ Efficient  │ Full     │
 │ Fragmentation                           │ Possible   │ None     │
 │ Speed (during transfer)                 │ Good       │ Better   │
 │ Suitable for low-space drives           │ Yes        │ No       │
 │ Suitable for high-speed seeding         │ Good       │ Better   │
 └─────────────────────────────────────────┴────────────┴──────────┘

 *Pre-allocation can take seconds to minutes for large files

Practical Example: 

 // For a 4GB movie download on a laptop
 // Use SPARSE (default) - quick to start, efficient space use
 AddTorrentParams params = new AddTorrentParams();
 // No need to set, SPARSE is default

 // For a 100GB archive on a dedicated NAS with 1TB free space
 // Use ALLOCATE - minimize fragmentation, maximize performance
 AddTorrentParams params = new AddTorrentParams();
 params.storageMode(StorageMode.STORAGE_MODE_ALLOCATE);

 // For temporary downloads on small USB drive
 // Use SPARSE - only allocate what you need
See Also:

  • Enum Constant Details

    • STORAGE_MODE_ALLOCATE

      public static final StorageMode STORAGE_MODE_ALLOCATE
      All pieces will be written to their final position, all files will be allocated in full when the torrent is first started. This is done with fallocate() and similar calls. This mode minimizes fragmentation.

    • STORAGE_MODE_SPARSE

      public static final StorageMode STORAGE_MODE_SPARSE
      All pieces will be written to the place where they belong and sparse files will be used. This is the recommended, and default mode.

    • UNKNOWN

      public static final StorageMode UNKNOWN
      Unknown storage mode (for error handling)

  • Method Details

    • values

      public static StorageMode[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static StorageMode valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • swig

      public int swig()
      Returns:
      the native value

    • fromSwig

      public static StorageMode fromSwig(int swigValue)
      Parameters:
      swigValue - the native value
      Returns:
      the java enum