nanomsg.org/go/mangos/v2@v2.0.9-0.20200203084354-8a092611e461/pipe.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  // Pipe represents the high level interface to a low level communications
    18  // channel.  There is one of these associated with a given TCP connection,
    19  // for example.  This interface is intended for application use.
    20  //
    21  // Note that applications cannot send or receive data on a Pipe directly.
    22  type Pipe interface {
    23  
    24  	// ID returns the numeric ID for this Pipe.  This will be a
    25  	// 31 bit (bit 32 is clear) value for the Pipe, which is unique
    26  	// across all other Pipe instances in the application, while
    27  	// this Pipe exists.  (IDs are recycled on Close, but only after
    28  	// all other Pipe values are used.)
    29  	ID() uint32
    30  
    31  	// Address returns the address (URL form) associated with the Pipe.
    32  	// This matches the string passed to Dial() or Listen().
    33  	Address() string
    34  
    35  	// GetOption returns an arbitrary option.  The details will vary
    36  	// for different transport types.
    37  	GetOption(name string) (interface{}, error)
    38  
    39  	// Listener returns the Listener for this Pipe, or nil if none.
    40  	Listener() Listener
    41  
    42  	// Dialer returns the Dialer for this Pipe, or nil if none.
    43  	Dialer() Dialer
    44  
    45  	// Close closes the Pipe.  This does a disconnect, or something similar.
    46  	// Note that if a dialer is present and active, it will redial.
    47  	Close() error
    48  }
    49  
    50  // PipeEvent determines what is actually transpiring on the Pipe.
    51  type PipeEvent int
    52  
    53  const (
    54  	// PipeEventAttaching is called before the Pipe is registered with the
    55  	// socket.  The intention is to permit the application to reject
    56  	// a pipe before it is attached.
    57  	PipeEventAttaching = iota
    58  
    59  	// PipeEventAttached occurs after the Pipe is attached.
    60  	// Consequently, it is possible to use the Pipe for delivering
    61  	// events to sockets, etc.
    62  	PipeEventAttached
    63  
    64  	// PipeEventDetached occurs after the Pipe has been detached
    65  	// from the socket.
    66  	PipeEventDetached
    67  )
    68  
    69  // PipeEventHook is an application supplied function to be called when
    70  // events occur relating to a Pipe.
    71  type PipeEventHook func(PipeEvent, Pipe)