src/lib/pubsub/pubsub_build.h

   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) */