mangos has been quite successful, but over the past several years we’ve worked on NNG and nanomsg, as well as mangos. We wanted to make some improvements, using what we learned, and some of those required breaking changes. Hence v2.
Version 1 is still available, so feel free to keep using it for now. (Eventually we’ll deprecate that in favor of v2, but until v2 fully stabilizes we’re not ready.)
The rest of this document is meant as a transition guide.
Some of this is still in transition, so YMMV.
Some support for older Go versions is being removed. Additionally, our adoption of new APIs means that older versions of Go won’t work.
Nobody was using, as it was a transition for a much older FFI based on nanomsg. That FFI has been abandonware for a long time.
Raw mode sockets are now in their own packages, e.g. xreq instead of req.
This is similar to the Martin’s original libnanomsg library.
The OptionRawMode option has transitioned to being read-only.
This API is being completely refactored, and should not be used. Don’t rely on it, new style protocols don’t implement it. (Soon none of the protocols will.)
For some protocols, we have removed irrelevant options. For example,
tuning the send queue depth (OptionWriteQLen) makes no sense for
the REQ protocol (not raw mode). Likewise OptionBestEffort makes
no sense with a broadcast protocol like SURVEYOR. So those options
will report an error now.
To facilitate some uses, the errors have been moved into their own package. There are still aliases left behind.
Some protocols (e.g. REQ, REP, SURVEYOR, and RESPONDENT) support the notion of Contexts. These can be opened on a socket, and each context maintains its own state, including outstanding request IDs, timers, and so forth.
This makes it possible (for exmaple) for many synchronous go routines
to share a single socket, each having it’s own context. See the
OpenContext() function in the protocol.ProtocolBase interface.
Protocols now return their numeric and string IDs, as well as those of
their APIs, via a new Info() API, which replaces the old Number(),
Name(), and similar APIs.
The old pipe.GetProp() API is changed so that Properties are formalized
as Options and a pipe.GetOpt() API is used to access them.
The xstar protocol implicitly retransmits / forwards received messages just like the cooked protocol. The fact that v1 did not do this was a bug.
When using vanilla Dialer.Dial(), the calling thread will normally
be blocked until either a connection is established, or an error
occurs on this first attempt. If an error occurs, there will be no
further retries. However, the self-healing mode is used for subsequent
connection attempts.
This mode is intended to facilitate folks who are trying to fix the most common connection setup errors.
An option, OptionDialAsynch, can be set on sockets or dialers to restore
the old behavior, where a dialer will just run in the background
from the beginning.
The Message.Port is changed to use a new Pipe interface, which has
some differences but conversion should be straight-forward. (Few
applications used this API.)
Also the PortHook API is now replaced with a PipeEventHook API,
and a separate event is used for pre-attach and post-attach. This
turns out to be useful in circumstances where one wants to be certain
that the pipe is connected before taking some action.
Note that Pipe.GetOption will fallback to looking for the Dialer or
Listener option if it doesn’t have a local value.
This API turns out to be not very useful, and we have elected to just eliminate it entirely. It was only intended for use by transports, and then only to cope with cases where a Message might have been stuck in a queue for a long time.
The ability to lookup protocol names by their protocol number is removed.
Each protocol instead has their identities (including name and string)
as constants (Self, Peer, SelfName, and PeerName) in the package.
To register a transport, just import the transport package. (You can
use an anonymous import (i.e. an underscore import) to bring transport
packages in. The AddTransport() method on sockets, and NewTransport()
method for transport packages have been removed. (Transport implementations
can register themselves with transport.RegisterTransport().)