Module openj9.criu
Package org.eclipse.openj9.criu

Class CRIUSupport

  • public final class CRIUSupport
extends Object
    CRIU Support API A checkpoint is the act of halting the JVM, saving its state and writing it out to a file(s). Restore is reading the saved checkpoint state and resuming the JVM application from when it was checkpointed. This technology is available via CRIU (checkpoint/restore in user space see, https://criu.org/Main_Page). This API enables the use of CRIU capabilities provided by the OS as well as JVM support for facilitating a successful checkpoint and restore in varying environments.

    • Constructor Detail

      • CRIUSupport

        public CRIUSupport​(Path imageDir)
        Constructs a new CRIUSupport. The default CRIU dump options are:

        imageDir = imageDir, the directory where the images are to be created.

        leaveRunning = false

        shellJob = false

        extUnixSupport = false

        logLevel = 2

        logFile = criu.log

        fileLocks = false

        ghostFileLimit = 1 MB

        workDir = imageDir, the directory where the images are to be created.

        Parameters:
        imageDir - the directory that will hold the dump files as a java.nio.file.Path
        Throws:
        NullPointerException - if imageDir is null
        SecurityException - if no permission to access imageDir or no CRIU_DUMP_PERMISSION
        IllegalArgumentException - if imageDir is not a valid directory

    • Method Detail

      • isCRIUSupportEnabled

        public static boolean isCRIUSupportEnabled()
        Queries if CRIU support is enabled and criu library has been loaded.
        Returns:
        TRUE if CRIU support is enabled and the library is loaded, FALSE otherwise

      • enableCRIUSecProvider

        public static boolean enableCRIUSecProvider()
        Checks if the CRIUSecProvider is enabled when CRIU checkpoints are allowed (checks whether -XX:-CRIUSecProvider has been specified).
        Returns:
        true if CRIUSecProvider is enabled, otherwise false

      • isCheckpointAllowed

        public static boolean isCheckpointAllowed()
        Queries if CRIU Checkpoint is allowed. With -XX:+CRIURestoreNonPortableMode enabled (default policy) only a single checkpoint is allowed.
        Returns:
        true if Checkpoint is allowed, otherwise false

      • getErrorMessage

        public static String getErrorMessage()
        Returns an error message describing why isCRIUSupportEnabled() returns false, and what can be done to remediate the issue.
        Returns:
        NULL if isCRIUSupportEnabled() returns true and nativeLoaded is true as well, otherwise the error message.

      • setLeaveRunning

        public CRIUSupport setLeaveRunning​(boolean leaveRunning)
        Controls whether process trees are left running after checkpoint.

        Default: false

        Parameters:
        leaveRunning -
        Returns:
        this

      • setShellJob

        public CRIUSupport setShellJob​(boolean shellJob)
        Controls ability to dump shell jobs.

        Default: false

        Parameters:
        shellJob -
        Returns:
        this

      • setExtUnixSupport

        public CRIUSupport setExtUnixSupport​(boolean extUnixSupport)
        Controls whether to dump only one end of a unix socket pair.

        Default: false

        Parameters:
        extUnixSupport -
        Returns:
        this

      • setLogLevel

        public CRIUSupport setLogLevel​(int logLevel)
        Sets the verbosity of log output. Available levels:
        1. Only errors
        2. Errors and warnings
        3. Above + information messages and timestamps
        4. Above + debug

        Default: 2

        Parameters:
        logLevel - verbosity from 1 to 4 inclusive
        Returns:
        this
        Throws:
        IllegalArgumentException - if logLevel is not valid

      • setLogFile

        public CRIUSupport setLogFile​(String logFile)
        Write log output to logFile.

        Default: criu.log

        Parameters:
        logFile - name of the file to write log output to. The path to the file can be set with setWorkDir(Path).
        Returns:
        this
        Throws:
        IllegalArgumentException - if logFile is null or a path

      • setFileLocks

        public CRIUSupport setFileLocks​(boolean fileLocks)
        Controls whether to dump file locks.

        Default: false

        Parameters:
        fileLocks -
        Returns:
        this

      • setTCPEstablished

        public CRIUSupport setTCPEstablished​(boolean tcpEstablished)
        Controls whether to re-establish TCP connects.

        Default: false

        Parameters:
        tcpEstablished -
        Returns:
        this

      • setAutoDedup

        public CRIUSupport setAutoDedup​(boolean autoDedup)
        Controls whether auto dedup of memory pages is enabled.

        Default: false

        Parameters:
        autoDedup -
        Returns:
        this

      • setTrackMemory

        public CRIUSupport setTrackMemory​(boolean trackMemory)
        Controls whether memory tracking is enabled.

        Default: false

        Parameters:
        trackMemory -
        Returns:
        this

      • setUnprivileged

        public CRIUSupport setUnprivileged​(boolean unprivileged)
        Controls whether CRIU will be invoked in privileged or unprivileged mode.

        Default: false

        Parameters:
        unprivileged -
        Returns:
        this

      • setGhostFileLimit

        public CRIUSupport setGhostFileLimit​(long limit)
        Set the size limit for ghost files when taking a checkpoint. File limit can not be greater than 2^32 - 1 or negative. Default: 1MB set by CRIU
        Parameters:
        limit - the file limit size in bytes.
        Returns:
        this
        Throws:
        UnsupportedOperationException - if file limit is greater than 2^32 - 1 or negative.

      • registerRestoreEnvFile

        public CRIUSupport registerRestoreEnvFile​(Path envFile)
        Append new environment variables to the set returned by ProcessEnvironment.getenv(...) upon restore. All pre-existing (environment variables from checkpoint run) env vars are retained. All environment variables specified in the envFile are added as long as they do not modifiy pre-existeing environment variables. Format for envFile is the following: ENV_VAR_NAME1=ENV_VAR_VALUE1 ... ENV_VAR_NAMEN=ENV_VAR_VALUEN OPENJ9_RESTORE_JAVA_OPTIONS is a special environment variable that can be used to add JVM options on restore.
        Parameters:
        envFile - The file that contains the new environment variables to be added
        Returns:
        this

      • registerRestoreOptionsFile

        public CRIUSupport registerRestoreOptionsFile​(Path optionsFile)
        Add new JVM options upon restore. The options will be specified in an options file with the form specified in https://www.eclipse.org/openj9/docs/xoptionsfile/ Only a subset of JVM options are available on restore. Consult the CRIU Support section of Eclipse OpenJ9 documentation to determine which options are supported.
        Parameters:
        optionsFile - The file that contains the new JVM options to be added on restore
        Returns:
        this

      • registerPostRestoreHook

        public CRIUSupport registerPostRestoreHook​(Runnable hook)
        User hook that is run after restoring a checkpoint image. This is equivalent to registerPostRestoreHook(hook, HookMode.SINGLE_THREAD_MODE, DEFAULT_SINGLE_THREAD_MODE_HOOK_PRIORITY); Hooks will be run in single threaded mode, no other application threads will be active. Users should avoid synchronization of objects that are not owned by the thread, terminally blocking operations and launching new threads in the hook. If the thread attempts to acquire a lock that it doesn't own, an exception will be thrown.
        Parameters:
        hook - user hook
        Returns:
        this

      • registerPostRestoreHook

        public CRIUSupport registerPostRestoreHook​(Runnable hook,
                                           CRIUSupport.HookMode mode,
                                           int priority)
                                    throws UnsupportedOperationException
        User hook that is run after restoring a checkpoint image. If SINGLE_THREAD_MODE is requested, no other application threads will be active. Users should avoid synchronization of objects that are not owned by the thread, terminally blocking operations and launching new threads in the hook. If the thread attempts to acquire a lock that it doesn't own, an exception will be thrown. If CONCURRENT_MODE is requested, the hook will be run alongside all other active Java threads. High-priority hooks are run first after restore, and vice-versa for low-priority hooks. The priority of the hook is with respect to the other hooks run within that mode. CONCURRENT_MODE hooks are implicitly lower priority than SINGLE_THREAD_MODE hooks. Ie. the lowest priority SINGLE_THREAD_MODE hook is a higher priority than the highest priority CONCURRENT_MODE hook. The hooks of the same mode with the same priority are run in random order.
        Parameters:
        hook - user hook
        mode - the mode in which the hook is run, either CONCURRENT_MODE or SINGLE_THREAD_MODE
        priority - the priority of the hook, between LOWEST_USER_HOOK_PRIORITY - HIGHEST_USER_HOOK_PRIORITY. Throws UnsupportedOperationException otherwise.
        Returns:
        this
        Throws:
        UnsupportedOperationException - if the hook mode is not SINGLE_THREAD_MODE or CONCURRENT_MODE or the priority is not between LOWEST_USER_HOOK_PRIORITY and HIGHEST_USER_HOOK_PRIORITY.

      • registerPreCheckpointHook

        public CRIUSupport registerPreCheckpointHook​(Runnable hook)
        User hook that is run before checkpointing the JVM. This is equivalent to registerPreCheckpointHook(hook, HookMode.SINGLE_THREAD_MODE, DEFAULT_SINGLE_THREAD_MODE_HOOK_PRIORITY). Hooks will be run in single threaded mode, no other application threads will be active. Users should avoid synchronization of objects that are not owned by the thread, terminally blocking operations and launching new threads in the hook. If the thread attempts to acquire a lock that it doesn't own, an exception will be thrown.
        Parameters:
        hook - user hook
        Returns:
        this

      • registerPreCheckpointHook

        public CRIUSupport registerPreCheckpointHook​(Runnable hook,
                                             CRIUSupport.HookMode mode,
                                             int priority)
                                      throws UnsupportedOperationException
        User hook that is run before checkpointing the JVM. If SINGLE_THREAD_MODE is requested, no other application threads will be active. Users should avoid synchronization of objects that are not owned by the thread, terminally blocking operations and launching new threads in the hook. If the thread attempts to acquire a lock that it doesn't own, an exception will be thrown. If CONCURRENT_MODE is requested, the hook will be run alongside all other active Java threads. High-priority hooks are run last before checkpoint, and vice-versa for low-priority hooks. The priority of the hook is with respect to the other hooks run within that mode. CONCURRENT_MODE hooks are implicitly lower priority than SINGLE_THREAD_MODEd hooks. Ie. the lowest priority SINGLE_THREAD_MODE hook is a higher priority than the highest priority CONCURRENT_MODE hook. The hooks of the same mode with the same priority are run in random order.
        Parameters:
        hook - user hook
        mode - the mode in which the hook is run, either CONCURRENT_MODE or SINGLE_THREAD_MODE
        priority - the priority of the hook, between LOWEST_USER_HOOK_PRIORITY - HIGHEST_USER_HOOK_PRIORITY. Throws UnsupportedOperationException otherwise.
        Returns:
        this
        Throws:
        UnsupportedOperationException - if the hook mode is not SINGLE_THREAD_MODE or CONCURRENT_MODE or the priority is not between LOWEST_USER_HOOK_PRIORITY and HIGHEST_USER_HOOK_PRIORITY.

      • checkpointJVM

        public void checkpointJVM()
        Checkpoint the JVM. This operation will use the CRIU options set by the options setters.
        Throws:
        UnsupportedOperationException - if CRIU is not supported or running in non-portable mode (only one checkpoint is allowed), and we have already checkpointed once.
        JVMCheckpointException - if a JVM error occurred before checkpoint
        SystemCheckpointException - if a System operation failed before checkpoint
        SystemRestoreException - if a System operation failed during or after restore
        JVMRestoreException - if an error occurred during or after restore