Tor 0.4.9.0-alpha-dev
pubsub.h
Go to the documentation of this file.
1/* Copyright (c) 2001, Matej Pfajfar.
2 * Copyright (c) 2001-2004, Roger Dingledine.
3 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4 * Copyright (c) 2007-2021, The Tor Project, Inc. */
5/* See LICENSE for licensing information */
6
7/**
8 * @file pubsub.h
9 * @brief Header for OO publish-subscribe functionality.
10 *
11 * This module provides a wrapper around the "dispatch" module,
12 * ensuring type-safety and allowing us to do static analysis on
13 * publication and subscriptions.
14 *
15 * With this module, we enforce:
16 * <ul>
17 * <li>that every message has (potential) publishers and subscribers;
18 * <li>that every message is published and subscribed from the correct
19 * channels, with the correct type ID, every time it is published.
20 * <li>that type IDs correspond to a single C type, and that the C types are
21 * used correctly.
22 * <li>that when a message is published or subscribed, it is done with
23 * a correct subsystem identifier
24 * </ul>
25 *
26 * We do this by making "publication requests" and "subscription requests"
27 * into objects, and doing some computation on them before we create
28 * a dispatch_t with them.
29 *
30 * Rather than using the dispatch module directly, a publishing module
31 * receives a "binding" object that it uses to send messages with the right
32 * settings.
33 *
34 * Most users of this module will want to use this header, and the
35 * pubsub_macros.h header for convenience.
36 */
37
38/*
39 *
40 * Overview: Messages are sent over channels. Before sending a message on a
41 * channel, or receiving a message on a channel, a subsystem needs to register
42 * that it publishes, or subscribes, to that message, on that channel.
43 *
44 * Messages, channels, and subsystems are represented internally as short
45 * integers, though they are associated with human-readable strings for
46 * initialization and debugging.
47 *
48 * When registering for a message, a subsystem must say whether it is an
49 * exclusive publisher/subscriber to that message type, or whether other
50 * subsystems may also publish/subscribe to it.
51 *
52 * All messages and their publishers/subscribers must be registered early in
53 * the initialization process.
54 *
55 * By default, it is an error for a message type to have publishers and no
56 * subscribers on a channel, or subscribers and no publishers on a channel.
57 *
58 * A subsystem may register for a message with a note that delivery or
59 * production is disabled -- for example, because the subsystem is
60 * disabled at compile-time. It is not an error for a message type to
61 * have all of its publishers or subscribers disabled.
62 *
63 * After a message is sent, it is delivered to every recipient. This
64 * delivery happens from the top level of the event loop; it may be
65 * interleaved with network events, timers, etc.
66 *
67 * Messages may have associated data. This data is typed, and is owned
68 * by the message. Strings, byte-arrays, and integers have built-in
69 * support. Other types may be added. If objects are to be sent,
70 * they should be identified by handle. If an object requires cleanup,
71 * it should be declared with an associated free function.
72 *
73 * Semantically, if two subsystems communicate only by this kind of
74 * message passing, neither is considered to depend on the other, though
75 * both are considered to have a dependency on the message and on any
76 * types it contains.
77 *
78 * (Or generational index?)
79 */
80#ifndef TOR_PUBSUB_PUBSUB_H
81#define TOR_PUBSUB_PUBSUB_H
82
88
89#endif /* !defined(TOR_PUBSUB_PUBSUB_H) */
Declaration of pub_binding_t.
Header for functions that add relationships to a pubsub builder.
Flags that can be set on publish/subscribe messages.
Macros to help with the publish/subscribe dispatch API.
Header for pubsub_publish.c.