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

Class CRIUSupport

java.lang.Object
org.eclipse.openj9.criu.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 Details

    • 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 Details

    • 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.

    • setImageDir

      public CRIUSupport setImageDir(Path imageDir)
      Sets the directory that will hold the images upon checkpoint. This must be set before calling checkpointJVM().
      Parameters:
      imageDir - the directory as a java.nio.file.Path
      Returns:
      this
      Throws:
      NullPointerException - if imageDir is null
      SecurityException - if no permission to access imageDir
      IllegalArgumentException - if imageDir is not a valid directory

    • 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

    • setWorkDir

      public CRIUSupport setWorkDir(Path workDir)
      Sets the directory where non-image files are stored (e.g. logs).

      Default: same as path set by setImageDir(Path).

      Parameters:
      workDir - the directory as a java.nio.file.Path
      Returns:
      this
      Throws:
      NullPointerException - if workDir is null
      SecurityException - if no permission to access workDir
      IllegalArgumentException - if workDir is not a valid directory

    • 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