Tor  0.4.4.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-2020, 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) */
Flags that can be set on publish/subscribe messages.
Declaration of pub_binding_t.
Macros to help with the publish/subscribe dispatch API.
Header for pubsub_publish.c.
Header for functions that add relationships to a pubsub builder.