The Go electron API: a tale of two brokers.

[aconway]

The Go binding for proton provides 2 alternate APIs, `proton` is an
exact analogue of the event-driven proton C API and `electron` which is
a more go-oriented, procedural API. The differences were motivated by
the concurrency features of the Go language but there may be lessons to
learn for other languages. Take a look at 

https://github.com/alanconway/qpid-proton/tree/master/examples/go


## A tale of two brokers

The `proton` and `electron` packages provide two alternate APIs for
AMQP applications.  See [the proton Go README](https://github.com/apach
e/qpid-proton/blob/master/proton
-c/bindings/go/src/qpid.apache.org/README.md) for a discussion of why
there are two APIs.

The examples `proton/broker.go` and `electron/broker.go` both implement
the same simple broker-like functionality using each of the two APIs.
They both handle multiple connections concurrently and store messages
on bounded queues implemented by Go channels.

However the `electron/broker` is less than half as long as the
`proton/broker` illustrating why it is better suited for most Go
applications.

`proton/broker` must explicitly handle proton events, which are
processed in a single goroutine per connection since proton is not
concurrent safe. Each connection uses channels to exchange messages
between the event-handling goroutine and the shared queues that are
accessible to all connections. Sending messages is particularly tricky
since we must monitor the queue for available messages and the sending
link for available credit in order to send messages.


`electron/broker` takes advantage of the `electron` package, which
hides all the event handling and passing of messages between goroutines
beind behind straightforward interfaces for sending and receiving
messages. The electron broker can implement links as simple goroutines
that loop popping messages from a queue and sending them or receiving
messages and pushing them to a queue.

The un-reactor

[aconway]

The proton reactor provides a complete solution for integrating foreign
IO into a single threaded proton event loop. This is useful in
situations where proton is being used in isolation, there is no other
IO handling framework available and everything is single threaded.

However often that is not going to be the case.  There are many
existing C and C++ libraries for managing polling of file descriptors
and dispatching of work, and most server applications that might want
to embed proton already have their own frameworks.

So I'm thinking about how we can make integrating proton into an
existing (possibly multi-threaded) framework easier. I think all it
requires is a few simple functions to pull data out of a file
descriptor as events and push data back into a file descriptor, and
make this easier than directly using the collector and transport.  I've
done it in Go already but I think it could be captured in C and C++ as
well.

Anyone already done something like this?

Cheers,
Alan.