[GR-64488] TruffleFile API does not allow discovery of free and used space on filesystem.

PullRequest: graal/20816

Author: tzezula

sdk/CHANGELOG.md

@@ -11,6 +11,7 @@ This changelog summarizes major changes between GraalVM SDK versions. The main f
 * GR-61448 Compilation id (`CompId`) was added to the `opt done` truffle compilation logs. This id matches the compilation id in the output of deoptimization, compilation and code cache logs on HotSpot and SubstrateVM.
 * GR-31495 Added the ability to specify language and instrument specific options using `Source.Builder.option(String, String)`. See the language and or tool specific documentation for available options. Available source options may also be reflected using `Instrument.getSourceOptions()` and `Language.getSourceOptions()`.
 * GR-55223 The option sandbox.MaxStackFrames is no longer mandatory for the UNTRUSTED polyglot sandbox policy thanks to improved deoptimization handling of compiled code.
+* GR-64488 FileSystem implementations can now provide disk-related metadata, including [total space](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html##getFileStoreTotalSpace(java.nio.file.Path)), [usable space](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html#getFileStoreUsableSpace(java.nio.file.Path)), [unallocated space](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html#getFileStoreUnallocatedSpace(java.nio.file.Path)), [block size](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html#getFileStoreBlockSize(java.nio.file.Path)), and [read-only status](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html#isFileStoreReadOnly(java.nio.file.Path)).
 
 ## Version 24.2.0
 * GR-54905 When using Truffle NFI with the Panama backend, native access must now be granted to the Truffle module instead of the NFI Panama module. Use the `--enable-native-access=org.graalvm.truffle` Java command line option to enable the native access for the NFI Panama backend.

sdk/src/org.graalvm.polyglot/snapshot.sigtest

@@ -707,12 +707,17 @@ meth public abstract java.nio.file.Path parsePath(java.lang.String)
 meth public abstract java.nio.file.Path parsePath(java.net.URI)
 meth public abstract java.nio.file.Path toAbsolutePath(java.nio.file.Path)
 meth public abstract void delete(java.nio.file.Path) throws java.io.IOException
+meth public boolean isFileStoreReadOnly(java.nio.file.Path) throws java.io.IOException
 meth public java.lang.String getMimeType(java.nio.file.Path)
 meth public java.lang.String getPathSeparator()
 meth public java.lang.String getSeparator()
 meth public java.nio.charset.Charset getEncoding(java.nio.file.Path)
 meth public java.nio.file.Path getTempDirectory()
 meth public java.nio.file.Path readSymbolicLink(java.nio.file.Path) throws java.io.IOException
+meth public long getFileStoreBlockSize(java.nio.file.Path) throws java.io.IOException
+meth public long getFileStoreTotalSpace(java.nio.file.Path) throws java.io.IOException
+meth public long getFileStoreUnallocatedSpace(java.nio.file.Path) throws java.io.IOException
+meth public long getFileStoreUsableSpace(java.nio.file.Path) throws java.io.IOException
 meth public static org.graalvm.polyglot.io.FileSystem allowInternalResourceAccess(org.graalvm.polyglot.io.FileSystem)
 meth public static org.graalvm.polyglot.io.FileSystem allowLanguageHomeAccess(org.graalvm.polyglot.io.FileSystem)
  anno 0 java.lang.Deprecated(boolean forRemoval=false, java.lang.String since="")

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/io/FileSystem.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -435,6 +435,96 @@ default boolean isSameFile(Path path1, Path path2, LinkOption... options) throws
         return toRealPath(path1, options).equals(toRealPath(path2, options));
     }
 
+    /**
+     * Returns the size, in bytes, of the file store that contains the given {@code path}. If the
+     * file store's size exceeds {@link Long#MAX_VALUE}, {@code Long.MAX_VALUE} is returned.
+     *
+     * @param path the path whose file store size is to be determined
+     * @return the size of the file store in bytes
+     * @throws UnsupportedOperationException if the file system does not support retrieving file
+     *             store information
+     * @throws IOException if an I/O error occurs while accessing the file store
+     * @throws SecurityException if the {@link FileSystem} implementation denied the operation
+     * @since 25.0.0
+     */
+    default long getFileStoreTotalSpace(Path path) throws IOException {
+        throw new UnsupportedOperationException("GetFileStoreTotalSpace is not supported");
+    }
+
+    /**
+     * Returns the number of unallocated bytes in the file store that contains the given
+     * {@code path}. The returned value represents the raw free space on the storage device,
+     * regardless of access permissions or user quotas. If the number of unallocated bytes exceeds
+     * {@link Long#MAX_VALUE}, {@code Long.MAX_VALUE} is returned. Note that the value may be
+     * imprecise, as it can change at any time due to external I/O operations, including those
+     * performed outside this virtual machine.
+     *
+     * @param path the path whose file store is to be queried
+     * @return the number of unallocated bytes
+     * @throws UnsupportedOperationException if the file system does not support retrieving file
+     *             store information
+     * @throws IOException if an I/O error occurs while accessing the file store
+     * @throws SecurityException if the {@link FileSystem} implementation denied the operation
+     * @since 25.0.0
+     */
+    default long getFileStoreUnallocatedSpace(Path path) throws IOException {
+        throw new UnsupportedOperationException("GetFileStoreUnallocatedSpace is not supported");
+    }
+
+    /**
+     * Returns the number of bytes available to this Java virtual machine on the file store that
+     * contains the given {@code path}. Unlike {@link #getFileStoreUnallocatedSpace(Path)}, this
+     * method accounts for operating system level restrictions, user quotas, and file system
+     * permissions, and therefore may return a smaller value. If the available space exceeds
+     * {@link Long#MAX_VALUE}, {@code Long.MAX_VALUE} is returned. Note that the returned value may
+     * be imprecise, as it can change at any time due to external I/O activity, including operations
+     * performed outside this virtual machine.
+     *
+     * @param path the path whose file store is to be queried
+     * @return the number of usable bytes available to this Java virtual machine
+     * @throws UnsupportedOperationException if the file system does not support retrieving file
+     *             store information
+     * @throws IOException if an I/O error occurs while accessing the file store
+     * @throws SecurityException if the {@link FileSystem} implementation denied the operation
+     * @since 25.0.0
+     */
+    default long getFileStoreUsableSpace(Path path) throws IOException {
+        throw new UnsupportedOperationException("GetFileStoreUsableSpace is not supported");
+    }
+
+    /**
+     * Returns the number of bytes per block in the file store that contains the given {@code path}.
+     *
+     * @param path the path whose file store is to be queried
+     * @return the block size
+     * @throws UnsupportedOperationException if the file system does not support retrieving file
+     *             store information
+     * @throws IOException if an I/O error occurs while accessing the file store
+     * @throws SecurityException if the {@link FileSystem} implementation denied the operation
+     * @since 25.0.0
+     */
+    default long getFileStoreBlockSize(Path path) throws IOException {
+        throw new UnsupportedOperationException("GetFileStoreBlockSize is not supported");
+    }
+
+    /**
+     * Determines whether the file store containing the given {@code path} is read-only.
+     * <p>
+     * Note that even if the file store is not read-only, individual write operations may still be
+     * denied due to restrictions imposed by the {@link FileSystem} implementation, operating system
+     * level policies, user quotas, or file system permissions.
+     *
+     * @param path the path whose file store is to be queried
+     * @throws UnsupportedOperationException if the file system does not support retrieving file
+     *             store information
+     * @throws IOException if an I/O error occurs while accessing the file store
+     * @throws SecurityException if the {@link FileSystem} implementation denied the operation
+     * @since 25.0.0
+     */
+    default boolean isFileStoreReadOnly(Path path) throws IOException {
+        throw new UnsupportedOperationException("IsFileStoreReadOnly is not supported");
+    }
+
     /**
      * Creates a {@link FileSystem} implementation based on the host Java NIO. The returned instance
      * can be used as a delegate by a decorating {@link FileSystem}.

truffle/CHANGELOG.md

@@ -22,6 +22,7 @@ This changelog summarizes major changes between Truffle versions relevant to lan
     * Automatic reference type tracking based on assumptions, eliminating redundant type checks.
     * Automatic single-assignment tracking based on assumptions allowing languages to assume that a property is effectively final (i.e. stays unchanged after the initial assignment) as well as constant-fold values of a constant receiver with a known shape.
     * You can still disable the new layout and switch back to the previous implementation using the system property: `-Dtruffle.object.LayoutFactory=com.oracle.truffle.api.object.CoreLayoutFactory`.
+* GR-64488 Added `TruffleFile#getFileStoreInfo()` providing access to disk-related metadata such as total size, usable space, unallocated space and block size.
 
 ## Version 24.2.0
 * GR-60636 Truffle now stops compiling when the code cache fills up on HotSpot. A warning is printed when that happens.