https://github.com/thefrontside/ctrlc-windows

Send a CTRL-C event to a Windows console application
https://github.com/thefrontside/ctrlc-windows

concurrency nodejs windows

Last synced: about 2 months ago
JSON representation

Send a CTRL-C event to a Windows console application

• Host: GitHub
• URL: https://github.com/thefrontside/ctrlc-windows
• Owner: thefrontside
• Created: 2020-10-29T15:03:36.000Z (almost 4 years ago)
• Default Branch: v2
• Last Pushed: 2022-09-20T20:41:02.000Z (about 2 years ago)
• Last Synced: 2024-07-22T03:03:45.617Z (2 months ago)
• Topics: concurrency, nodejs, windows
• Language: Rust
• Size: 285 KB
• Stars: 9
• Watchers: 4
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md

Awesome Lists containing this project

README

        
# 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

``` javascript

import { ctrlc } from 'ctrlc-windows';

export function gracefulShutdown(process) {

  if (process.platform === 'win32') {

    ctrlc(process.pid);

  } else {

    process.kill();

  }

}

```