G::Publisher Class Reference

A broadcast communication channel between unrelated processes using shared memory. More...

#include <gpublisher.h>

Public Member Functions
	Publisher (const std::string &channel_name, bool auto_cleanup=true)
	Constructor for a publisher.
	Publisher (const std::string &channel_name, Item publisher_info, bool auto_cleanup=true)
	A constructor overload including arbitrary "info" metadata that is stored in the channel (subject to buffer size limits). More...
	~Publisher ()
	Destructor. More...
void	publish (const char *p, size_t n, const char *type=nullptr)
	Publishes a chunk of data to subscribers.
void	publish (const std::vector< char > &, const char *type=nullptr)
	Publishes a chunk of data to subscribers.
void	publish (const std::vector< std::pair< const char *, size_t > > &, const char *type)
	Publishes segmented data to subscribers.
void	publish (const std::vector< std::vector< char > > &, const char *type)
	Publishes chunked data to subscribers.

Static Public Member Functions
static std::vector< std::string >	list (std::vector< std::string > *others=nullptr)
	Returns a list of channel names. More...
static void	purge (const std::string &channel_name)
	Tries to clean up any failed slots in the named channel. More...
static std::string	delete_ (const std::string &channel_name)
	Deletes the channel. More...
static Item	info (const std::string &channel_name, bool all_slots=true)
	Returns a variant containing information about the state of the channel. More...

Detailed Description

A broadcast communication channel between unrelated processes using shared memory.

The shared memory name is public so that subscribers can find it (see shm_open()). Subscribers are then notified via individual unix-domain sockets.

Communication is message-based and unreliable; newer messages will overwrite older ones if not consumed. Messages have an associated type name.

There are two shared memory segments per channel; one control and one data. This allows the data segment to be discarded and replaced if it is too small.

The named sockets are created by the subscribers, their name is put into the shared memory segment, and they are unlinked by the publisher on first use. Consequently, sockets exist in the filesystem in the interval between binding by the subscriber and the next publish event in the publisher.

As the publisher goes away it marks the shared memory as defunct, notifies subscribers one last time, and unlinks the shared memory from the filesystem. It also unlinks any sockets that have not been previously unlinked.

Definition at line 67 of file gpublisher.h.

Constructor & Destructor Documentation

G::Publisher::Publisher	(	const std::string &	channel_name,
		G::Item	info,
		bool	auto_cleanup = true
	)

A constructor overload including arbitrary "info" metadata that is stored in the channel (subject to buffer size limits).

The metadata is enriched with a "type" field that is initialised with the basename of argv0.

Definition at line 221 of file gpublisher.cpp.

G::Publisher::~Publisher

(

)

Destructor.

Marks the shared memory as defunct and sends out notification to subscribers causing their receive()s to return false.

Any recent subscribers that have never been publish()ed to before will get a notification and as a result their named sockets will be unlink()d. This means that the subscribers do not have to do any special filesystem cleanup themselves.

Definition at line 231 of file gpublisher.cpp.

Member Function Documentation

std::string G::Publisher::delete_ ( const std::string &  channel_name )

static

Deletes the channel.

This should only be run administratively. Returns a failure reason on error.

Definition at line 303 of file gpublisher.cpp.

G::Item G::Publisher::info ( const std::string &  channel_name, bool  all_slots = true  )

static

Returns a variant containing information about the state of the channel.

The 'publisher' sub-item is the metadata from the constructor, enriched with a "pid" field that is the publisher's process id.

Definition at line 293 of file gpublisher.cpp.

std::vector< std::string > G::Publisher::list ( std::vector< std::string > *  others = nullptr )

static

Returns a list of channel names.

Optionally returns by reference a list of visible-but-unreadable channels.

Definition at line 288 of file gpublisher.cpp.

void G::Publisher::purge ( const std::string &  channel_name )

static

Tries to clean up any failed slots in the named channel.

This should only be run administratively because it is the subscribers' job to clean up after themselves.

Definition at line 298 of file gpublisher.cpp.

---

The documentation for this class was generated from the following files:

• /home/graeme/videotools/src/glib/gpublisher.h
• /home/graeme/videotools/src/glib/gpublisher.cpp