nanomsg.org/go/mangos/v2@v2.0.9-0.20200203084354-8a092611e461/transport.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 // XXX: The interfaces listed here will eventually move to the Transport 18 // package, to be named without the Tran prefix, and then this file will 19 // go away. 20 21 // TranPipe behaves like a full-duplex message-oriented connection between two 22 // peers. Callers may call operations on a Pipe simultaneously from 23 // different goroutines. (These are different from net.Conn because they 24 // provide message oriented semantics.) 25 // 26 // Pipe is only intended for use by transport implementors, and should 27 // not be directly used in applications. 28 type TranPipe interface { 29 30 // Send sends a complete message. In the event of a partial send, 31 // the Pipe will be closed, and an error is returned. For reasons 32 // of efficiency, we allow the message to be sent in a scatter/gather 33 // list. 34 Send(*Message) error 35 36 // Recv receives a complete message. In the event that either a 37 // complete message could not be received, an error is returned 38 // to the caller and the Pipe is closed. 39 // 40 // To mitigate Denial-of-Service attacks, we limit the max message 41 // size to 1M. 42 Recv() (*Message, error) 43 44 // Close closes the underlying transport. Further operations on 45 // the Pipe will result in errors. Note that messages that are 46 // queued in transport buffers may still be received by the remote 47 // peer. 48 Close() error 49 50 // GetOption returns an arbitrary transport specific option on a 51 // pipe. Options for pipes are read-only and specific to that 52 // particular connection. If the property doesn't exist, then 53 // ErrBadOption should be returned. 54 GetOption(string) (interface{}, error) 55 } 56 57 // TranDialer represents the client side of a connection. Clients initiate 58 // the connection. 59 // 60 // TranDialer is only intended for use by transport implementors, and should 61 // not be directly used in applications. 62 type TranDialer interface { 63 // Dial is used to initiate a connection to a remote peer. 64 Dial() (TranPipe, error) 65 66 // SetOption sets a local option on the dialer. 67 // ErrBadOption can be returned for unrecognized options. 68 // ErrBadValue can be returned for incorrect value types. 69 SetOption(name string, value interface{}) error 70 71 // GetOption gets a local option from the dialer. 72 // ErrBadOption can be returned for unrecognized options. 73 GetOption(name string) (value interface{}, err error) 74 } 75 76 // TranListener represents the server side of a connection. Servers respond 77 // to a connection request from clients. 78 // 79 // TranListener is only intended for use by transport implementors, and should 80 // not be directly used in applications. 81 type TranListener interface { 82 83 // Listen actually begins listening on the interface. It is 84 // called just prior to the Accept() routine normally. It is 85 // the socket equivalent of bind()+listen(). 86 Listen() error 87 88 // Accept completes the server side of a connection. Once the 89 // connection is established and initial handshaking is complete, 90 // the resulting connection is returned to the client. 91 Accept() (TranPipe, error) 92 93 // Close ceases any listening activity, and will specifically close 94 // any underlying file descriptor. Once this is done, the only way 95 // to resume listening is to create a new Server instance. Presumably 96 // this function is only called when the last reference to the server 97 // is about to go away. Established connections are unaffected. 98 Close() error 99 100 // SetOption sets a local option on the listener. 101 // ErrBadOption can be returned for unrecognized options. 102 // ErrBadValue can be returned for incorrect value types. 103 SetOption(name string, value interface{}) error 104 105 // GetOption gets a local option from the listener. 106 // ErrBadOption can be returned for unrecognized options. 107 GetOption(name string) (value interface{}, err error) 108 109 // Address gets the local address. The value may not be meaningful 110 // until Listen() has been called. 111 Address() string 112 } 113 114 // Transport is the interface for transport suppliers to implement. 115 type Transport interface { 116 // Scheme returns a string used as the prefix for SP "addresses". 117 // This is similar to a URI scheme. For example, schemes can be 118 // "tcp" (for "tcp://xxx..."), "ipc", "inproc", etc. 119 Scheme() string 120 121 // NewDialer creates a new Dialer for this Transport. 122 NewDialer(url string, sock Socket) (TranDialer, error) 123 124 // NewListener creates a new PipeListener for this Transport. 125 // This generally also arranges for an OS-level file descriptor to be 126 // opened, and bound to the the given address, as well as establishing 127 // any "listen" backlog. 128 NewListener(url string, sock Socket) (TranListener, error) 129 }