go.nanomsg.org/mangos/v3@v3.4.3-0.20240217232803-46464076f1f5/socket.go (about) 1 // Copyright 2018 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 // Socket is the main access handle applications use to access the SP 18 // system. It is an abstraction of an application's "connection" to a 19 // messaging topology. Applications can have more than one Socket open 20 // at a time. 21 type Socket interface { 22 // Info returns information about the protocol (numbers and names) 23 // and peer protocol. 24 Info() ProtocolInfo 25 26 // Close closes the open Socket. Further operations on the socket 27 // will return ErrClosed. 28 Close() error 29 30 // Send puts the message on the outbound send queue. It blocks 31 // until the message can be queued, or the send deadline expires. 32 // If a queued message is later dropped for any reason, 33 // there will be no notification back to the application. 34 Send([]byte) error 35 36 // Recv receives a complete message. The entire message is received. 37 Recv() ([]byte, error) 38 39 // SendMsg puts the message on the outbound send. It works like Send, 40 // but allows the caller to supply message headers. AGAIN, the Socket 41 // ASSUMES OWNERSHIP OF THE MESSAGE. 42 SendMsg(*Message) error 43 44 // RecvMsg receives a complete message, including the message header, 45 // which is useful for protocols in raw mode. 46 RecvMsg() (*Message, error) 47 48 // Dial connects a remote endpoint to the Socket. The function 49 // returns immediately, and an asynchronous goroutine is started to 50 // establish and maintain the connection, reconnecting as needed. 51 // If the address is invalid, then an error is returned. 52 Dial(addr string) error 53 54 DialOptions(addr string, options map[string]interface{}) error 55 56 // NewDialer returns a Dialer object which can be used to get 57 // access to the underlying configuration for dialing. 58 NewDialer(addr string, options map[string]interface{}) (Dialer, error) 59 60 // Listen connects a local endpoint to the Socket. Remote peers 61 // may connect (e.g. with Dial) and will each be "connected" to 62 // the Socket. The accepter logic is run in a separate goroutine. 63 // The only error possible is if the address is invalid. 64 Listen(addr string) error 65 66 ListenOptions(addr string, options map[string]interface{}) error 67 68 NewListener(addr string, options map[string]interface{}) (Listener, error) 69 70 // GetOption is used to retrieve an option for a socket. 71 GetOption(name string) (interface{}, error) 72 73 // SetOption is used to set an option for a socket. 74 SetOption(name string, value interface{}) error 75 76 // OpenContext creates a new Context. If a protocol does not 77 // support separate contexts, this will return an error. 78 OpenContext() (Context, error) 79 80 // SetPipeEventHook sets a PipeEventHook function to be called when a 81 // Pipe is added or removed from this socket (connect/disconnect). 82 // The previous hook is returned (nil if none.) (Only one hook can 83 // be used at a time.) 84 SetPipeEventHook(PipeEventHook) PipeEventHook 85 } 86 87 // Context is a protocol context, and represents the upper side operations 88 // that applications will want to use. Every socket has a default context, 89 // but only a certain protocols will allow the creation of additional 90 // Context instances (only if separate stateful contexts make sense for 91 // a given protocol). 92 type Context interface { 93 94 // Close closes the open Socket. Further operations on the socket 95 // will return ErrClosed. 96 Close() error 97 98 // GetOption is used to retrieve an option for a socket. 99 GetOption(name string) (interface{}, error) 100 101 // SetOption is used to set an option for a socket. 102 SetOption(name string, value interface{}) error 103 104 // Send puts the message on the outbound send queue. It blocks 105 // until the message can be queued, or the send deadline expires. 106 // If a queued message is later dropped for any reason, 107 // there will be no notification back to the application. 108 Send([]byte) error 109 110 // Recv receives a complete message. The entire message is received. 111 Recv() ([]byte, error) 112 113 // SendMsg puts the message on the outbound send. It works like Send, 114 // but allows the caller to supply message headers. AGAIN, the Socket 115 // ASSUMES OWNERSHIP OF THE MESSAGE. 116 SendMsg(*Message) error 117 118 // RecvMsg receives a complete message, including the message header, 119 // which is useful for protocols in raw mode. 120 RecvMsg() (*Message, error) 121 }