msgrtr

Documentation

Overview

Provides a message routing interface. The user application invokes the Start() function to begin listening using http on the given port. Messages received are 'unpacked' and then routed to the user application's threads.

The 'url' passed on the start call is the only one which is supported. Threads in the application can register and provide a channel on which event structures are delivered for matching events. The registration defines the 'path' which match messages (e.g. network/router/add). Paths may be 'short' (e.g. network/router) to receive all messages which match to that depth. Multiple listeners can register for the same path; all messages are 'broadcast' to all listeners; there is no concept of bubble up or handling which prevent the event from being delivered to some of the listeners.

The listening thread can respond (reply) to an event, and at least one listener must reply if the ack field is set to true. If no listeners reply the sending application will hang until timeout. Only one reply per event is sent, the first, all others are silently discarded. Replys are sent by using the event's reply function.

Event messages are expected to be posted to the url as a json object with some known set of fields, and optionally some meta information which the listener(s) may need. The 'band' field describes the 'path' (e.g. network/router) and the action type will be appended to the path provided that the action is not empty or missing.

When an event is received it is written on the channel of all listeners which have registered for the event type. The contents pushed on the channel is a *msgrtr.Event which has public fields so that they are easily accessed by the user programme. Speifically, the event type and paylod are probably what is of the most interest. The payload is is a map, indexed by string, which references interface{} elements. The event type is the _complete_ type; not just the portion of the type that the listener registered. For example, if the listener registered network.swtich (wanting all events for network switches) the event types generated would include: network.switch.add, network.switch.del network.switch.mod, etc. If a listener registers only for a specific type, then that will be the only type delivered.

The third field of interest, and to which the user process must pay attention to, is the Ack field. If true, one of the listeners _must_ call event.Reply() to send a reply to the sender.

Event types are determined by the message generator, the process sending the http request to this process, and are _not_ controlled by this package. Same goes for the payload map. The keys are up to the message generator.

The user programme may specify an optional data item (probably a pointer to struct, but it can be anything) when an event registration is made. This data item is then included when the event is sent to the listener allowing the listener to avoid having to depend on global data whenever possible. To support this, the struct passed to a listener for an event is actually of tyep *Envelope which is stuffed with the even and data item.

Index

• Constants
• func Register(band string, ch chan *Envelope, ldata interface{})
• func Start(port string, url string, usr_sheep *bleater.Bleater) chan *ipc.Chmsg
• func Unregister(band string, ch chan *Envelope)
• type Data_block
• type Envelope
• type Event
  • func (e *Event) Get_msg() string
  • func (e *Event) Path() string
  • func (e *Event) Reply(state string, msg string, data string)
  • func (e *Event) String() string
• type Reg_msg

Constants

const (
	NOP       int = 0
	SEND_ACK  int = iota // user send an ack
	RAW_BLOCK            // raw data block from http
	REGISTER             // listener thread registration
	UNREGISTER
)

Functions

func Register

func Register(band string, ch chan *Envelope, ldata interface{})

A wrapper allowing a user thread to register with a function call rather than having to send a message to the dispatcher.

func Start

func Start(port string, url string, usr_sheep *bleater.Bleater) chan *ipc.Chmsg

Initialises the message router and returns the channel that it will accept retquest (ipc structs) on allowing the user thread(s) to register for messages. Port is the port that the http listener should camp on, and url is the url string that should be used. Port may be of either of these two forms:

interface:port
port

If interface is supplied, then the listener will be started only on that interface/port combination. If interface is omitted, then the listener will listen on all interfaces. This function may be invoked multiple times, with different ports, but be advised that all messages are funneled to the same handler. Multiple invocations only serve to establish different interfaces and/or ports.

func Unregister

func Unregister(band string, ch chan *Envelope)

A wrapper allowing a user thread to unregister with a function call rather than having to send a message to the dispatcher.

Types

type Data_block

type Data_block struct {
	Events []*Event // events from the json http message (unmarshal)
	// contains filtered or unexported fields
}

Block passed to the dispatcher to, well, dispatch.

type Envelope

type Envelope struct {
	Event *Event      // the event received
	Ldata interface{} // user data that the listener registered with their channel
}

Envelope wraps an event such that user's data can be passed to each listener without exposing it and without the need to duplicate the event.

type Event

type Event struct {
	Event_type string                 // dot separated 'path' or band (e.g. network.router.add)
	Ack        bool                   // true an ack is expected by a listener
	Payload    map[string]interface{} // event message content
	// contains filtered or unexported fields
}

An event expected on a POST request. Multiple events may be bundled int a single data block as an array.

func (*Event) Get_msg

func (e *Event) Get_msg() string

Returns the currently formatted message.

func (*Event) Path

func (e *Event) Path() string

Path returns the path of this event.

func (*Event) Reply

func (e *Event) Reply(state string, msg string, data string)

Reply sends a reply back to the http requestor. This is a wrapper that puts a request on the dispatcher queue so that we serialise the access to the underlying data block. Status is presumed to be OK or ERROR or somesuch. msg is any string that is a 'commment' and data is json or other data (not quoted in the output).

func (*Event) String

func (e *Event) String() string

String returns a string describing the instance of the structure.

type Reg_msg

type Reg_msg struct {
	// contains filtered or unexported fields
}

Message user app sends to register for a message or set of messages.