go.nanomsg.org/mangos/v3@v3.4.3-0.20240217232803-46464076f1f5/protocol.go (about) 1 // Copyright 2022 The Mangos Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use file except in compliance with the License. 5 // You may obtain a copy of the license at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 package mangos 16 17 // ProtocolPipe represents the handle that a Protocol implementation has 18 // to the underlying stream transport. It can be thought of as one side 19 // of a TCP, IPC, or other type of connection. 20 type ProtocolPipe interface { 21 // ID returns a unique 31-bit value associated with this. 22 // The value is unique for a given socket, at a given time. 23 ID() uint32 24 25 // Close does what you think. 26 Close() error 27 28 // SendMsg sends a message. On success it returns nil. This is a 29 // blocking call. 30 SendMsg(*Message) error 31 32 // RecvMsg receives a message. It blocks until the message is 33 // received. On error, the pipe is closed and nil is returned. 34 RecvMsg() *Message 35 36 // SetPrivate is used to set protocol private data. 37 SetPrivate(interface{}) 38 39 // GetPrivate returns the previously stored protocol private data. 40 GetPrivate() interface{} 41 } 42 43 // ProtocolInfo is a description of the protocol. 44 type ProtocolInfo struct { 45 Self uint16 46 Peer uint16 47 SelfName string 48 PeerName string 49 } 50 51 // ProtocolContext is a "context" for a protocol, which contains the 52 // various stateful operations such as timers, etc. necessary for 53 // running the protocol. This is separable from the protocol itself 54 // as the protocol may permit the creation of multiple contexts. 55 type ProtocolContext interface { 56 // Close closes the context. 57 Close() error 58 59 // SendMsg sends the message. The message may be queued, or 60 // may be delivered immediately, depending on the nature of 61 // the protocol. On success, the context assumes ownership 62 // of the message. On error, the caller retains ownership, 63 // and may either resend the message or dispose of it otherwise. 64 SendMsg(*Message) error 65 66 // RecvMsg receives a complete message, including the message header, 67 // which is useful for protocols in raw mode. 68 RecvMsg() (*Message, error) 69 70 // GetOption is used to retrieve the current value of an option. 71 // If the protocol doesn't recognize the option, EBadOption should 72 // be returned. 73 GetOption(string) (interface{}, error) 74 75 // SetOption is used to set an option. EBadOption is returned if 76 // the option name is not recognized, EBadValue if the value is 77 // invalid. 78 SetOption(string, interface{}) error 79 } 80 81 // ProtocolBase provides the protocol-specific handling for sockets. 82 // This is the new style API for sockets, and is how protocols provide 83 // their specific handling. 84 type ProtocolBase interface { 85 ProtocolContext 86 87 // Info returns the information describing this protocol. 88 Info() ProtocolInfo 89 90 // XXX: Revisit these when we can use Pipe natively. 91 92 // AddPipe is called when a new Pipe is added to the socket. 93 // Typically, this is as a result of connect or accept completing. 94 // The pipe ID will be unique for the socket at this time. 95 // The implementation must not call back into the socket, but it 96 // may reject the pipe by returning a non-nil result. 97 AddPipe(ProtocolPipe) error 98 99 // RemovePipe is called when a Pipe is removed from the socket. 100 // Typically, this indicates a disconnected or closed connection. 101 // This is called exactly once, after the underlying transport pipe 102 // is closed. The Pipe ID will still be valid. 103 RemovePipe(ProtocolPipe) 104 105 // OpenContext is a request to create a unique instance of the 106 // protocol state machine, allowing concurrent use of states on 107 // a given protocol socket. Protocols that don't support this 108 // should return ErrProtoOp. 109 OpenContext() (ProtocolContext, error) 110 } 111 112 // Useful constants for protocol numbers. Note that the major protocol number 113 // is stored in the upper 12 bits, and the minor (subprotocol) is located in 114 // the bottom 4 bits. 115 const ( 116 ProtoPair = 0x10 117 ProtoPair1 = 0x11 118 ProtoPub = 0x20 119 ProtoSub = 0x21 120 ProtoReq = 0x30 121 ProtoRep = 0x31 122 ProtoPush = 0x50 123 ProtoPull = 0x51 124 ProtoSurveyor = 0x62 125 ProtoRespondent = 0x63 126 ProtoBus = 0x70 127 ProtoStar = 0x640 // Experimental! 128 )