Tor
0.4.6.0-alpha-dev
lib
pubsub
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
83
#include "
lib/pubsub/pub_binding_st.h
"
84
#include "
lib/pubsub/pubsub_connect.h
"
85
#include "
lib/pubsub/pubsub_flags.h
"
86
#include "
lib/pubsub/pubsub_macros.h
"
87
#include "
lib/pubsub/pubsub_publish.h
"
88
89
#endif
/* !defined(TOR_PUBSUB_PUBSUB_H) */
pubsub_publish.h
Header for pubsub_publish.c.
pubsub_flags.h
Flags that can be set on publish/subscribe messages.
pubsub_macros.h
Macros to help with the publish/subscribe dispatch API.
pub_binding_st.h
Declaration of pub_binding_t.
pubsub_connect.h
Header for functions that add relationships to a pubsub builder.
Generated by
1.8.20