pubsub.h (3672B)
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 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) */