go.nanomsg.org/mangos/v3@v3.4.3-0.20240217232803-46464076f1f5/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().)