nanomsg.org/go/mangos/v2@v2.0.9-0.20200203084354-8a092611e461/CHANGES-v2.adoc (about)

     1  
     2  = Changes in Version 2
     3  
     4  mangos has been quite successful, but over the past several years we've
     5  worked on NNG and nanomsg, as well as mangos.  We wanted to make some
     6  improvements, using what we learned, and some of those required breaking
     7  changes.  Hence v2.
     8  
     9  Version 1 is still available, so feel free to keep using it for now.
    10  (Eventually we'll deprecate that in favor of v2, but until v2 fully
    11  stabilizes we're not ready.)
    12  
    13  The rest of this document is meant as a transition guide.
    14  
    15  Some of this is still in transition, so YMMV.
    16  
    17  == Import path changed
    18  
    19  Use `nanomsg.org/go/mangos/v2` as the base URL for imports.
    20  
    21  == Go v1.9 Or Better Required
    22  
    23  Some support for older Go versions is being removed.  Additionally,
    24  our adoption of new APIs means that older versions of Go won't work.
    25  
    26  == `compat` Package Removed
    27  
    28  Nobody was using, as it was a transition for a much older FFI based
    29  on nanomsg.  That FFI has been abandonware for a long time.
    30  
    31  == New Raw Mode Packages
    32  
    33  Raw mode sockets are now in their own packages, e.g. `xreq` instead of `req`.
    34  This is similar to the Martin's original libnanomsg library.
    35  
    36  The `OptionRawMode` option has transitioned to being read-only.
    37  
    38  == `Protocol` API mostly removed
    39  
    40  This API is being completely refactored, and should not be used.
    41  Don't rely on it, new style protocols don't implement it.  (Soon
    42  none of the protocols will.)
    43  
    44  == Removal of Some Irrelevant Options
    45  
    46  For some protocols, we have removed irrelevant options.  For example,
    47  tuning the send queue depth (`OptionWriteQLen`) makes no sense for
    48  the `REQ` protocol (not raw mode).  Likewise `OptionBestEffort` makes
    49  no sense with a broadcast protocol like `SURVEYOR`.  So those options
    50  will report an error now.
    51  
    52  == `errors` package
    53  
    54  To facilitate some uses, the errors have been moved into their own
    55  package.  There are still aliases left behind.
    56  
    57  == New Context Support
    58  
    59  Some protocols (e.g. REQ, REP, SURVEYOR, and RESPONDENT) support the
    60  notion of Contexts.  These can be opened on a socket, and each context
    61  maintains its own state, including outstanding request IDs, timers, and
    62  so forth.
    63  
    64  This makes it possible (for exmaple) for many synchronous go routines
    65  to share a single socket, each having it's own context.  See the
    66  `OpenContext()` function in the `protocol.ProtocolBase` interface.
    67  
    68  == Info API Changed
    69  
    70  Protocols now return their numeric and string IDs, as well as those of
    71  their APIs, via a new `Info()` API, which replaces the old `Number()`,
    72  `Name()`, and similar APIs.
    73  
    74  == Properties API Merged into Options
    75  
    76  The old `pipe.GetProp()` API is changed so that Properties are formalized
    77  as Options and a `pipe.GetOpt()` API is used to access them.
    78  
    79  == STAR Raw Mode Fixed
    80  
    81  The xstar protocol implicitly retransmits / forwards received messages
    82  just like the cooked protocol.  The fact that v1 did not do this was
    83  a bug.
    84  
    85  == Dial Now Synchronous
    86  
    87  When using vanilla `Dialer.Dial()`, the calling thread will normally
    88  be blocked until either a connection is established, or an error
    89  occurs on this first attempt.  If an error occurs, there will be no
    90  further retries.  However, the self-healing mode is used for subsequent
    91  connection attempts.
    92  
    93  This mode is intended to facilitate folks who are trying to fix the most
    94  common connection setup errors.
    95  
    96  An option, `OptionDialAsynch`, can be set on sockets or dialers to restore
    97  the old behavior, where a dialer will just run in the background
    98  from the beginning.
    99  
   100  == Port API changed to Pipe
   101  
   102  The `Message.Port` is changed to use a new `Pipe` interface, which has
   103  some differences but conversion should be straight-forward.  (Few
   104  applications used this API.)
   105  
   106  Also the `PortHook` API is now replaced with a `PipeEventHook` API,
   107  and a separate event is used for pre-attach and post-attach.  This
   108  turns out to be useful in circumstances where one wants to be certain
   109  that the pipe is connected before taking some action.
   110  
   111  Note that `Pipe.GetOption` will fallback to looking for the `Dialer` or
   112  `Listener` option if it doesn't have a local value.
   113  
   114  == `Message.Expired` removed
   115  
   116  This API turns out to be not very useful, and we have elected to just
   117  eliminate it entirely.  It was only intended for use by transports,
   118  and then only to cope with cases where a Message might have been stuck
   119  in a queue for a long time.
   120  
   121  == `Protocol.ProtocolName` removed
   122  
   123  The ability to lookup protocol names by their protocol number is removed.
   124  Each protocol instead has their identities (including name and string)
   125  as constants (`Self`, `Peer`, `SelfName`, and `PeerName`) in the package.
   126  
   127  == Simplified Transport registration
   128  
   129  To register a transport, just import the transport package.  (You can
   130  use an anonymous import (i.e. an underscore import) to bring transport
   131  packages in.  The `AddTransport()` method on sockets, and `NewTransport()`
   132  method for transport packages have been removed.  (Transport implementations
   133  can register themselves with transport.RegisterTransport().)