Dart ProcessSignal

last modified April 4, 2025

The ProcessSignal class in Dart provides a way to handle operating system process signals. It allows graceful shutdown and custom signal handling.

Process signals are notifications sent to a program by the operating system. Common signals include SIGINT (Ctrl+C) and SIGTERM (termination request).

Basic Definition

ProcessSignal represents operating system signals that can be sent to a process. It's part of Dart's dart:io library for server-side applications.

Key features include signal watching, graceful shutdown handling, and platform- specific signal support. Not all signals are available on all platforms.

Handling SIGINT (Ctrl+C)

This example shows basic SIGINT (Ctrl+C) signal handling in Dart.

import 'dart:io';

void main() async {
  ProcessSignal.sigint.watch().listen((signal) {
    print('\nReceived SIGINT (signal $signal)');
    print('Performing cleanup...');
    exit(0);
  });

  print('Press Ctrl+C to send SIGINT');
  await Future.delayed(Duration(minutes: 1));
}

We set up a listener for SIGINT signals. When Ctrl+C is pressed, our handler executes cleanup code before exiting. The program waits for user input.

$ dart main.dart
Press Ctrl+C to send SIGINT
^C
Received SIGINT (signal ProcessSignal_SIGINT)
Performing cleanup...

Handling Multiple Signals

This example demonstrates handling multiple signals with one listener.

import 'dart:io';

void main() async {
  final signals = [ProcessSignal.sigterm, ProcessSignal.sighup];
  
  for (var signal in signals) {
    signal.watch().listen((_) {
      print('Received ${signal.toString()}');
      exit(0);
    });
  }

  print('Running (PID: ${pid})');
  print('Send SIGTERM or SIGHUP to terminate');
  await Future.delayed(Duration(minutes: 1));
}

We create listeners for both SIGTERM and SIGHUP signals. Either signal will trigger the same shutdown procedure. The program displays its process ID.

$ dart main.dart
Running (PID: 12345)
Send SIGTERM or SIGHUP to terminate
Received ProcessSignal_SIGTERM

Graceful Shutdown

This example implements a graceful shutdown with cleanup operations.

import 'dart:io';

class Server {
  Future<void> cleanup() async {
    print('Closing database connections...');
    await Future.delayed(Duration(seconds: 1));
    print('Saving state...');
    await Future.delayed(Duration(seconds: 1));
    print('Cleanup complete');
  }
}

void main() async {
  final server = Server();
  
  ProcessSignal.sigterm.watch().listen((_) async {
    print('\nShutdown initiated');
    await server.cleanup();
    exit(0);
  });

  print('Server running (PID: ${pid})');
  print('Send SIGTERM to terminate gracefully');
  await Future.delayed(Duration(minutes: 1));
}

We create a server class with cleanup operations. When SIGTERM is received, it performs async cleanup before exiting. This ensures data integrity.

$ dart main.dart
Server running (PID: 12345)
Send SIGTERM to terminate gracefully
Shutdown initiated
Closing database connections...
Saving state...
Cleanup complete

Ignoring Signals

This example shows how to ignore certain signals in your application.

import 'dart:io';

void main() async {
  // Ignore SIGINT (Ctrl+C)
  ProcessSignal.sigint.watch().listen((_) {
    print('\nSIGINT ignored (use SIGTERM to terminate)');
  });

  ProcessSignal.sigterm.watch().listen((_) {
    print('\nReceived SIGTERM - shutting down');
    exit(0);
  });

  print('Running (PID: ${pid})');
  print('Try Ctrl+C - it will be ignored');
  await Future.delayed(Duration(minutes: 1));
}

We ignore SIGINT (Ctrl+C) while still handling SIGTERM. This creates a more controlled shutdown process requiring specific termination signals.

$ dart main.dart
Running (PID: 12345)
Try Ctrl+C - it will be ignored
^C
SIGINT ignored (use SIGTERM to terminate)
Received SIGTERM - shutting down

Platform-Specific Signals

This example demonstrates platform-specific signal handling in Dart.

import 'dart:io';

void main() async {
  // Platform-specific signals
  final signals = [
    if (Platform.isLinux || Platform.isMacOS) ProcessSignal.sigusr1,
    if (Platform.isWindows) ProcessSignal.sigbreak,
  ];

  for (var signal in signals) {
    signal.watch().listen((_) {
      print('Received ${signal.toString()}');
      // Custom handling for each signal
    });
  }

  print('Running on ${Platform.operatingSystem}');
  print('Send platform-specific signals');
  await Future.delayed(Duration(minutes: 1));
}

We handle different signals based on the platform. Linux/macOS uses SIGUSR1, while Windows uses SIGBREAK. The code adapts to the current platform.

$ dart main.dart
Running on linux
Send platform-specific signals
Received ProcessSignal_SIGUSR1

Best Practices

• Clean shutdown: Always perform cleanup in signal handlers
• Async handling: Use async/await for cleanup operations
• Platform awareness: Check signal availability per platform
• Signal documentation: Document expected signals in your app

Source

Dart ProcessSignal Documentation

This tutorial covered Dart's ProcessSignal class with practical examples showing signal handling, graceful shutdowns, and platform-specific considerations.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Dart tutorials.