signal_notify.pony

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
use @getpid[I32]()
use @kill[I32](pid_t: I32, sig: U32)
use @raise[I32](sig: U32)

primitive SignalSubscriberLimit
  """
  The per-signal subscriber limit (16) was already reached. A later
  registration for the same signal can succeed once a current subscriber
  unsubscribes.
  """

primitive SignalRegistrationRefused
  """
  The operating system refused the registration. Retrying will not
  succeed.
  """

type SignalRegistrationError is
  (SignalSubscriberLimit | SignalRegistrationRefused)
  """
  Why a `SignalHandler`'s registration could not be completed.
  """

interface SignalNotify
  """
  Notifications for a signal.
  """
  fun ref apply(count: U32): Bool =>
    """
    Called with the number of times the signal has fired since this was
    last called. Return false to stop listening for the signal.

    Delivery batching differs by platform: on Linux, macOS, and the BSDs
    several firings that arrive close together can be reported in one call
    with `count` greater than one, while on Windows each firing is a
    separate call with a `count` of one.
    """
    true

  fun ref registration_failed(reason: SignalRegistrationError) =>
    """
    Called when the handler's registration could not be completed.
    `SignalSubscriberLimit` is transient — a slot may open once another
    subscriber unsubscribes; `SignalRegistrationRefused` is permanent, so
    re-registering the same signal will fail again. The handler is then
    disposed — `disposed` follows once the runtime confirms it, and `apply`
    will not have run. If the handler was explicitly disposed before the
    failure was delivered, only `disposed` is called.
    """
    None

  fun ref disposed() =>
    """
    Called when the runtime has finished unregistering the handler,
    whichever way disposal began: explicitly via `SignalHandler.dispose`,
    when `apply` returned false, or when the registration could not be
    completed (preceded by `registration_failed` in that case). `apply`
    will never be called after this.

    By the time this is called, the handler no longer affects signal
    delivery: if it was the signal's last subscriber, the signal's
    disposition from before it was first handled has been restored. For
    most signals that is the operating system default, so raising a
    terminating one from here ends the process; for a signal the runtime
    keeps ignored, such as SIGPIPE, it is SIG_IGN. A handler disposed while
    the runtime itself is shutting down may never receive this call.
    """
    None

primitive SignalRaise
  """
  Raise a signal.

  Unlike SignalHandler, this accepts a raw signal number rather than a
  HandleableSignal. Raising fatal signals (e.g. SIGABRT to intentionally crash)
  is a legitimate operation — it is only handling them via the ASIO
  mechanism that is prevented.

  The raise is process-wide: every currently subscribed handler for the
  signal is notified. With no subscribers, the signal's current disposition
  applies — the operating system default for most signals (process death for
  a terminating one), but SIG_IGN for one the runtime keeps ignored like
  SIGPIPE.
  """
  fun apply(auth: SignalAuth, sig: U32) =>
    ifdef osx then
      // On Darwin, @raise delivers the signal to the current thread, not the
      // process, but kqueue EVFILT_SIGNAL will only see signals delivered to
      // the process. @kill delivers the signal to a specific process.
      @kill(@getpid(), sig)
    else
      @raise(sig)
    end