ceph/src/spdk/doc/notify.md

   1 # Notify library {#notify}
   2 The notify library implements an event bus, allowing users to register, generate,
   3 and listen for events. For example, the bdev library may register a new event type
   4 for bdev creation. Any time a bdev is created, it "sends" the event. Consumers of
   5 that event may periodically poll for new events to retrieve them.
   6 The event bus is implemented as a circular ring of fixed size. If event consumers
   7 do not poll frequently enough, events may be lost. All events are identified by a
   8 monotonically increasing integer, so missing events may be detected, although
   9 not recovered.
  10
  11 # Register event types {#notify_register}
  12
  13 During initialization the sender library should register its own event types using
  14 `spdk_notify_type_register(const char *type)`. Parameter 'type' is the name of
  15 notification type.
  16
  17 # Get info about events {#notify_get_info}
  18
  19 A consumer can get information about the available event types during runtime using
  20 `spdk_notify_foreach_type`, which iterates over registered notification types and
  21 calls a callback on each of them, so that user can produce detailed information
  22 about notification.
  23
  24 # Get new events {#notify_listen}
  25
  26 A consumer can get events by calling function `spdk_notify_foreach_event`.
  27 The caller should specify last received event and the maximum number of invocations.
  28 There might be multiple consumers of each event. The event bus is implemented as a
  29 circular buffer, so older events may be overwritten by newer ones.
  30
  31 # Send events {#notify_send}
  32
  33 When an event occurs, a library can invoke `spdk_notify_send` with two strings.
  34 One containing the type of the event, like "spdk_bdev_register", second with context,
  35 for example "Nvme0n1"
  36
  37 # RPC Calls {#rpc_calls}
  38
  39 See [JSON-RPC documentation](jsonrpc.md/#rpc_get_notification_types)