Macros | Typedefs | Functions
pubsub_build.h File Reference

Header used for constructing the OO publish-subscribe facility. More...

#include "lib/dispatch/msgtypes.h"

Go to the source code of this file.


#define pubsub_builder_free(db)    FREE_AND_NULL(pubsub_builder_t, pubsub_builder_free_, (db))
#define pubsub_connector_free(c)    FREE_AND_NULL(struct pubsub_connector_t, pubsub_connector_free_, (c))
#define pubsub_items_free(cfg)    FREE_AND_NULL(pubsub_items_t, pubsub_items_free_, (cfg))


typedef struct pubsub_builder_t pubsub_builder_t
typedef struct pubsub_items_t pubsub_items_t


pubsub_builder_tpubsub_builder_new (void)
int pubsub_builder_check (pubsub_builder_t *)
void pubsub_builder_free_ (pubsub_builder_t *)
struct pubsub_connector_tpubsub_connector_for_subsystem (pubsub_builder_t *, subsys_id_t)
void pubsub_connector_free_ (struct pubsub_connector_t *)
struct dispatch_tpubsub_builder_finalize (pubsub_builder_t *, pubsub_items_t **items_out)
void pubsub_items_clear_bindings (pubsub_items_t *items)
void pubsub_items_free_ (pubsub_items_t *cfg)

Detailed Description

Header used for constructing the OO publish-subscribe facility.

(See pubsub.h for more general information on this API.)

Definition in file pubsub_build.h.

Macro Definition Documentation

◆ pubsub_builder_free

#define pubsub_builder_free (   db)     FREE_AND_NULL(pubsub_builder_t, pubsub_builder_free_, (db))

Free a pubsub builder. This should only happen on error paths, where we have decided not to construct a dispatcher for some reason.

Definition at line 50 of file pubsub_build.h.

◆ pubsub_connector_free

#define pubsub_connector_free (   c)     FREE_AND_NULL(struct pubsub_connector_t, pubsub_connector_free_, (c))

The main-init code does this after subsystem initialization.

Definition at line 67 of file pubsub_build.h.

◆ pubsub_items_free

#define pubsub_items_free (   cfg)     FREE_AND_NULL(pubsub_items_t, pubsub_items_free_, (cfg))

Release all storage held in a pubsub_items_t.

Additionally, set the pointer cfg to NULL.

Definition at line 93 of file pubsub_build.h.

Typedef Documentation

◆ pubsub_builder_t

A "dispatch builder" is an incomplete dispatcher, used when registering messages. It does not have the same integrity guarantees as a dispatcher. It cannot actually handle messages itself: once all subsystems have registered, it is converted into a dispatch_t.

Definition at line 1 of file pubsub_build.h.

◆ pubsub_items_t

A "pubsub items" holds the configuration items used to configure a pubsub_builder. After the builder is finalized, this field is extracted, and used later to tear down pointers that enable publishing.

Definition at line 1 of file pubsub_build.h.

Function Documentation

◆ pubsub_builder_check()

int pubsub_builder_check ( pubsub_builder_t builder)


Check builder for consistency and various constraints. Return 0 on success, -1 on failure.

Definition at line 399 of file pubsub_check.c.

◆ pubsub_builder_finalize()

struct dispatch_t* pubsub_builder_finalize ( pubsub_builder_t builder,
pubsub_items_t **  items_out 

Constructs a dispatcher from a dispatch_builder, after checking that the invariances on the messages, channels, and connections have been respected.

This should happen after every subsystem has initialized, and before entering the mainloop.

Create a new dispatcher as configured in a pubsub_builder_t.

Consumes and frees its input.

Definition at line 278 of file pubsub_build.c.

Referenced by tor_mainloop_connect_pubsub().

◆ pubsub_builder_free_()

void pubsub_builder_free_ ( pubsub_builder_t pb)

Internal implementation of pubsub_builder_free().

Release all storage held by a pubsub_builder_t.

You'll (mostly) only want to call this function on an error case: if you're constructing a dispatch_t instead, you should call pubsub_builder_finalize() to consume the pubsub_builder_t.

Definition at line 74 of file pubsub_build.c.

◆ pubsub_builder_new()

pubsub_builder_t* pubsub_builder_new ( void  )

Create a new pubsub_builder. This should only happen in the main-init code.

Construct and return a new pubsub_builder_t.

Definition at line 56 of file pubsub_build.c.

Referenced by pubsub_install().

◆ pubsub_connector_for_subsystem()

struct pubsub_connector_t* pubsub_connector_for_subsystem ( pubsub_builder_t builder,
subsys_id_t  subsys 

Create a pubsub connector that a single subsystem will use to register its messages. The main-init code does this during subsystem initialization.

Create and return a pubsub_connector_t for the subsystem with ID subsys to use in adding publications, subscriptions, and types to builder.

Definition at line 89 of file pubsub_build.c.

◆ pubsub_connector_free_()

void pubsub_connector_free_ ( pubsub_connector_t con)

Release all storage held by a pubsub_connector_t.

Definition at line 107 of file pubsub_build.c.

◆ pubsub_items_clear_bindings()

void pubsub_items_clear_bindings ( pubsub_items_t items)

Clear all pub_binding_t backpointers in items.

Remove the dispatch_ptr fields for all the relevant publish bindings in items. The prevents subsequent dispatch_pub_() calls from sending messages to a dispatcher that has been freed.

Definition at line 263 of file pubsub_build.c.

◆ pubsub_items_free_()

void pubsub_items_free_ ( pubsub_items_t cfg)

Release all storage held in a pubsub_items_t.

Definition at line 42 of file pubsub_build.c.