ctrlc-windows

ctrlc-windows

Send CTRL-C to a Windows console application

Long running stateful processes like servers often hold a lot of system resources that they need to operate. These are things like communication ports, file descriptors, database connections, etc... At some point, when it is time for that process to shut it needs to release all those resources back to the operating system and exit. This process of freeing up all the things that were being used is called "graceful shutdown" and is really important to get right in systems that start and stop processes repeatedly. On Unix systems, the method for achieving a graceful shutdown of a process is to send it a signal (usually either SIGINT or SIGTERM).

The process can then register a handler for this signal which releases any resources that it is holding and exits.

The alternative to a graceful shutdown is a "forced termination". This is what happens when a process is unable to respond to a interrupt or termination signal. In this case, the process is ended immediately without the opprotunity to release any of the resources it holds.

On Unix systems, when you invoke process.kill() on a ChildProcess object, it sends the SIGTERM signal. That way, if the process has a SIGTERM handler it has an opportunity to perform a graceful shutdown.

Windows on the other hand, does not have a method to send signals to a process, so when you invoke the same process.kill() function on that platform, what you end up with is a forceful termination without any cleanup. However, Windows does have a method for applications to shutdown gracefully, namely hitting CTRL-C on the console to which the process is attached. And that's what this is all about. In fact, whenever you hit CTRL-C on a windows console that is running a node application, node will translate that CTRL-C into a SIGINT and dispatch any SIGINT handlers that it has registered. Since most well-behaved long-running Nodejs processes respond to SIGINT, this allows them to shutdown too.

This module exports a single ctrlc function which accepts a process id, and sends a CTRL-C event to that console.

Note: This is a no-op on non-windows platforms

Usage

import { ctrlc } from 'ctrlc-windows';

export function gracefulShutdown(process) {
  if (process.platform === 'win32') {
    ctrlc(process.pid);
  } else {
    process.kill();
  }
}