tor

The Tor anonymity network
git clone https://git.dasho.dev/tor.git
Log | Files | Refs | README | LICENSE

pubsub_build.h (3059B)

      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_build.h
      9 * @brief Header used for constructing the OO publish-subscribe facility.
     10 *
     11 * (See pubsub.h for more general information on this API.)
     12 **/
     13 
     14 #ifndef TOR_PUBSUB_BUILD_H
     15 #define TOR_PUBSUB_BUILD_H
     16 
     17 #include "lib/dispatch/msgtypes.h"
     18 
     19 struct dispatch_t;
     20 struct pubsub_connector_t;
     21 
     22 /**
     23 * A "dispatch builder" is an incomplete dispatcher, used when
     24 * registering messages.  It does not have the same integrity guarantees
     25 * as a dispatcher.  It cannot actually handle messages itself: once all
     26 * subsystems have registered, it is converted into a dispatch_t.
     27 **/
     28 typedef struct pubsub_builder_t pubsub_builder_t;
     29 
     30 /**
     31 * A "pubsub items" holds the configuration items used to configure a
     32 * pubsub_builder.  After the builder is finalized, this field is extracted,
     33 * and used later to tear down pointers that enable publishing.
     34 **/
     35 typedef struct pubsub_items_t pubsub_items_t;
     36 
     37 /**
     38 * Create a new pubsub_builder. This should only happen in the
     39 * main-init code.
     40 */
     41 pubsub_builder_t *pubsub_builder_new(void);
     42 
     43 /** DOCDOC */
     44 int pubsub_builder_check(pubsub_builder_t *);
     45 
     46 /**
     47 * Free a pubsub builder.  This should only happen on error paths, where
     48 * we have decided not to construct a dispatcher for some reason.
     49 */
     50 #define pubsub_builder_free(db) \
     51  FREE_AND_NULL(pubsub_builder_t, pubsub_builder_free_, (db))
     52 
     53 /** Internal implementation of pubsub_builder_free(). */
     54 void pubsub_builder_free_(pubsub_builder_t *);
     55 
     56 /**
     57 * Create a pubsub connector that a single subsystem will use to
     58 * register its messages.  The main-init code does this during subsystem
     59 * initialization.
     60 */
     61 struct pubsub_connector_t *pubsub_connector_for_subsystem(pubsub_builder_t *,
     62                                                          subsys_id_t);
     63 
     64 /**
     65 * The main-init code does this after subsystem initialization.
     66 */
     67 #define pubsub_connector_free(c) \
     68  FREE_AND_NULL(struct pubsub_connector_t, pubsub_connector_free_, (c))
     69 
     70 void pubsub_connector_free_(struct pubsub_connector_t *);
     71 
     72 /**
     73 * Constructs a dispatcher from a dispatch_builder, after checking that the
     74 * invariances on the messages, channels, and connections have been
     75 * respected.
     76 *
     77 * This should happen after every subsystem has initialized, and before
     78 * entering the mainloop.
     79 */
     80 struct dispatch_t *pubsub_builder_finalize(pubsub_builder_t *,
     81                                           pubsub_items_t **items_out);
     82 
     83 /**
     84 * Clear all pub_binding_t backpointers in <b>items</b>.
     85 **/
     86 void pubsub_items_clear_bindings(pubsub_items_t *items);
     87 
     88 /**
     89 * @copydoc pubsub_items_free_
     90 *
     91 * Additionally, set the pointer <b>cfg</b> to NULL.
     92 **/
     93 #define pubsub_items_free(cfg) \
     94  FREE_AND_NULL(pubsub_items_t, pubsub_items_free_, (cfg))
     95 void pubsub_items_free_(pubsub_items_t *cfg);
     96 
     97 #endif /* !defined(TOR_PUBSUB_BUILD_H) */