psuspend
v2.2.0
Published
Ultimate process pause & resume library for NodeJS
Downloads
10
Maintainers
Readme
PSuspend 2
Pause and resume processes on all hosts, including Windows!
Notice
On Windows, this uses PsSuspend, a part of PsTools by Mark Russinovich from Windows SysInternals. Using the lib methods counts as accepting the EULA for this software. The latest version + EULA will be stealthily downloaded, or if unavailable a version included with this package will be used. Both methods are quite efficient (~800 KB). You may, and are encouraged to, show the EULA to the end user (see below) or sysadmin.
Usage
// es6
import suspend from "psuspend";
// commonjs
// const suspend = require("psuspend").default;
let process = require("child_process").exec(/* ... */);
suspend(process); // suspend
suspend(process, false); // unsuspend
let pid = 12345;
suspend(pid); // suspend PID 12345
suspend(pid, false); // unsuspend PID 12345
suspend(pid).then(() => {
console.log("Suspended");
});
Agent
The agent is the active backend for the PSuspend API. You can access it like so:
const agent = suspend.agent;
agent.type; // "unix" or "pstools"
// "unix" method is a polyfill
// for non-windows hosts and requires
// no dependencies or initialization
Lazy Init
The suspend agent is lazy-init,
meaning that the first call to suspend
will take a slightly longer amount
of time than each subsequent call. If this is not desirable, call agent.init
when appropriate:
await suspend.agent.init(); // agent is ready to be used after this point
// OR
suspend.agent.init().catch(console.error); // agent is scheduled to initialize
You can also, if you prefer, use agent.cleanup
when you are sure that the
agent will not be used for a long time. The agent will also cleanup automatically
at the end of the active process. Using the agent after it is cleaned will cause
it to re-initialize.
await suspend.agent.cleanup();
EULA
To pass on the active agent's EULA to the end user:
if (suspend.agent.hasEula()) {
const eula = await suspend.agent.getEula();
console.log(eula); // Sysinternals Software License Terms...
}
Using the agent (suspend
, agent.suspend
, agent.unsuspend
) effectively
accepts the EULA.
Config
The configuration is only evaluated when the agent is initialized. See this section for info on when init occurs and how to forcefully reschedule it.
// Since v2.1.0
// Disable fetching the latest binary from the internet,
// always use the bundled version
suspend.config.set("onlyOffline", true);
// Since v2.1.0
// Compatibility with the "ntsuspend" module on Windows.
// If this is not set to NONE, "ntsuspend" MUST
// be installed, otherwise you will get errors! It is
// an optional dependency since v2.1.0. It should
// be installed unless you specifically exclude optional
// dependencies, or are running this on a non-Windows system,
// in which case this config option is ignored.
// 0 : NONE (default)
// 1 : BELOW_WIN8_1 (only below Windows 8.1)
// 2 : ALWAYS
suspend.config.set("ntsInterop", NtSuspendInteropMode.BELOW_WIN8_1);
Why not just ntsuspend?
The methods used by ntsuspend
(NtSuspendProcess
, NtResumeProcess
) are deprecated components of the
Win32 API, and while removal of these methods is at the moment unlikely,
their use is discouraged. PsSuspend
has been sanctioned and maintained by
Microsoft and supports Windows 8.1 and higher (but may likely work on
versions as low as Windows 2000). If supporting older versions is important for
your project, consider ntsuspend either standalone or the ntsInterop
option
in the config.