Documentation
¶
Overview ¶
Package flipcall implements a protocol providing Fast Local Interprocess Procedure Calls between mutually-distrusting processes.
Example ¶
const (
reqPrefix = "request "
respPrefix = "response "
count = 3
maxMessageLen = len(respPrefix) + 1 // 1 digit
)
pwa, err := NewPacketWindowAllocator()
if err != nil {
panic(err)
}
defer pwa.Destroy()
pwd, err := pwa.Allocate(PacketWindowLengthForDataCap(uint32(maxMessageLen)))
if err != nil {
panic(err)
}
var clientEP Endpoint
if err := clientEP.Init(ClientSide, pwd); err != nil {
panic(err)
}
defer clientEP.Destroy()
var serverEP Endpoint
if err := serverEP.Init(ServerSide, pwd); err != nil {
panic(err)
}
defer serverEP.Destroy()
var serverRun sync.WaitGroup
serverRun.Add(1)
go func() {
defer serverRun.Done()
i := 0
var buf bytes.Buffer
// wait for first request
n, err := serverEP.RecvFirst()
if err != nil {
return
}
for {
// read request
buf.Reset()
buf.Write(serverEP.Data()[:n])
fmt.Println(buf.String())
// write response
buf.Reset()
fmt.Fprintf(&buf, "%s%d", respPrefix, i)
copy(serverEP.Data(), buf.Bytes())
// send response and wait for next request
n, err = serverEP.SendRecv(uint32(buf.Len()))
if err != nil {
return
}
i++
}
}()
defer func() {
serverEP.Shutdown()
serverRun.Wait()
}()
// establish connection as client
if err := clientEP.Connect(); err != nil {
panic(err)
}
var buf bytes.Buffer
for i := 0; i < count; i++ {
// write request
buf.Reset()
fmt.Fprintf(&buf, "%s%d", reqPrefix, i)
copy(clientEP.Data(), buf.Bytes())
// send request and wait for response
n, err := clientEP.SendRecv(uint32(buf.Len()))
if err != nil {
panic(err)
}
// read response
buf.Reset()
buf.Write(clientEP.Data()[:n])
fmt.Println(buf.String())
}
Output: request 0 response 0 request 1 response 1 request 2 response 2
Index ¶
- Constants
- func PacketWindowLengthForDataCap(dataCap uint32) int
- type DatagramReader
- type DatagramWriter
- type Endpoint
- func (ep *Endpoint) Connect() error
- func (ep *Endpoint) Data() (bs []byte)
- func (ep *Endpoint) DataCap() uint32
- func (ep *Endpoint) Destroy()
- func (ep *Endpoint) Init(side EndpointSide, pwd PacketWindowDescriptor, opts ...EndpointOption) error
- func (ep *Endpoint) NewReader(dataLen uint32) *DatagramReader
- func (ep *Endpoint) NewWriter() *DatagramWriter
- func (ep *Endpoint) RecvFirst() (uint32, error)
- func (ep *Endpoint) SendLast(dataLen uint32) error
- func (ep *Endpoint) SendRecv(dataLen uint32) (uint32, error)
- func (ep *Endpoint) SendRecvFast(dataLen uint32) (uint32, error)
- func (ep *Endpoint) Shutdown()
- type EndpointOption
- type EndpointSide
- type PacketWindowAllocator
- type PacketWindowDescriptor
- type ShutdownError
Examples ¶
Constants ¶
const ( // PacketHeaderBytes is the size of a flipcall packet header in bytes. The // maximum datagram size supported by a flipcall connection is equal to the // length of the packet window minus PacketHeaderBytes. // // PacketHeaderBytes is exported to support its use in constant // expressions. Non-constant expressions may prefer to use // PacketWindowLengthForDataCap(). PacketHeaderBytes = 16 )
Packets consist of a 16-byte header followed by an arbitrarily-sized datagram. The header consists of:
A 4-byte native-endian connection state.
A 4-byte native-endian datagram length in bytes.
8 reserved bytes.
Variables ¶
This section is empty.
Functions ¶
func PacketWindowLengthForDataCap ¶
PacketWindowLengthForDataCap returns the minimum packet window size required to accommodate datagrams of the given size in bytes.
Types ¶
type DatagramReader ¶
type DatagramReader struct {
// contains filtered or unexported fields
}
DatagramReader implements io.Reader by reading a datagram from an Endpoint's packet window. Its use is optional; users that can use Endpoint.Data() more efficiently are advised to do so.
func (*DatagramReader) Init ¶
func (r *DatagramReader) Init(ep *Endpoint, dataLen uint32)
Init must be called on zero-value DatagramReaders before first use.
Preconditions: dataLen is 0, or was returned by a previous call to ep.RecvFirst() or ep.SendRecv().
func (*DatagramReader) Read ¶
func (r *DatagramReader) Read(dst []byte) (int, error)
Read implements io.Reader.Read.
func (*DatagramReader) Reset ¶
func (r *DatagramReader) Reset(dataLen uint32)
Reset causes r to begin reading a new datagram of the given length from the associated Endpoint.
Preconditions: dataLen is 0, or was returned by a previous call to the associated Endpoint's RecvFirst() or SendRecv() methods.
type DatagramWriter ¶
type DatagramWriter struct {
// contains filtered or unexported fields
}
DatagramWriter implements io.Writer by writing a datagram to an Endpoint's packet window. Its use is optional; users that can use Endpoint.Data() more efficiently are advised to do so.
func (*DatagramWriter) Init ¶
func (w *DatagramWriter) Init(ep *Endpoint)
Init must be called on zero-value DatagramWriters before first use.
func (*DatagramWriter) Len ¶
func (w *DatagramWriter) Len() uint32
Len returns the length of the written datagram.
func (*DatagramWriter) Reset ¶
func (w *DatagramWriter) Reset()
Reset causes w to begin writing a new datagram to the associated Endpoint.
type Endpoint ¶
type Endpoint struct {
// contains filtered or unexported fields
}
An Endpoint provides the ability to synchronously transfer data and control to a connected peer Endpoint, which may be in another process.
Since the Endpoint control transfer model is synchronous, at any given time one Endpoint "has control" (designated the active Endpoint), and the other is "waiting for control" (designated the inactive Endpoint). Users of the flipcall package designate one Endpoint as the client, which is initially active, and the other as the server, which is initially inactive. See flipcall_example_test.go for usage.
func NewEndpoint ¶
func NewEndpoint(side EndpointSide, pwd PacketWindowDescriptor, opts ...EndpointOption) (*Endpoint, error)
NewEndpoint is a convenience function that returns an initialized Endpoint allocated on the heap.
func (*Endpoint) Connect ¶
Connect blocks until the peer Endpoint has called Endpoint.RecvFirst().
Preconditions:
- ep is a client Endpoint.
- ep.Connect(), ep.RecvFirst(), ep.SendRecv(), and ep.SendLast() have never been called.
func (*Endpoint) Data ¶
Data returns the datagram part of ep's packet window as a byte slice.
Note that the packet window is shared with the potentially-untrusted peer Endpoint, which may concurrently mutate the contents of the packet window. Thus:
Readers must not assume that two reads of the same byte in Data() will return the same result. In other words, readers should read any given byte in Data() at most once.
Writers must not assume that they will read back the same data that they have written. In other words, writers should avoid reading from Data() at all.
func (*Endpoint) DataCap ¶
DataCap returns the maximum datagram size supported by ep. Equivalently, DataCap returns len(ep.Data()).
func (*Endpoint) Destroy ¶
func (ep *Endpoint) Destroy()
Destroy releases resources owned by ep. No other Endpoint methods may be called after Destroy.
func (*Endpoint) Init ¶
func (ep *Endpoint) Init(side EndpointSide, pwd PacketWindowDescriptor, opts ...EndpointOption) error
Init must be called on zero-value Endpoints before first use. If it succeeds, ep.Destroy() must be called once the Endpoint is no longer in use.
pwd represents the packet window used to exchange data with the peer Endpoint. FD may differ between Endpoints if they are in different processes, but must represent the same file. The packet window must initially be filled with zero bytes.
func (*Endpoint) NewReader ¶
func (ep *Endpoint) NewReader(dataLen uint32) *DatagramReader
NewReader is a convenience function that returns an initialized DatagramReader allocated on the heap.
Preconditions: dataLen was returned by a previous call to ep.RecvFirst() or ep.SendRecv().
func (*Endpoint) NewWriter ¶
func (ep *Endpoint) NewWriter() *DatagramWriter
NewWriter is a convenience function that returns an initialized DatagramWriter allocated on the heap.
func (*Endpoint) RecvFirst ¶
RecvFirst blocks until the peer Endpoint calls Endpoint.SendRecv(), then returns the datagram length specified by that call.
Preconditions:
- ep is a server Endpoint.
- ep.SendRecv(), ep.RecvFirst(), and ep.SendLast() have never been called.
func (*Endpoint) SendLast ¶
SendLast causes the peer Endpoint's call to Endpoint.SendRecv() or Endpoint.RecvFirst() to return with the given datagram length.
Preconditions:
- dataLen <= ep.DataCap().
- No previous call to ep.SendRecv() or ep.RecvFirst() has returned an error.
- ep.SendLast() has never been called.
- If ep is a client Endpoint, ep.Connect() has previously been called and returned nil.
func (*Endpoint) SendRecv ¶
SendRecv transfers control to the peer Endpoint, causing its call to Endpoint.SendRecv() or Endpoint.RecvFirst() to return with the given datagram length, then blocks until the peer Endpoint calls Endpoint.SendRecv() or Endpoint.SendLast().
Preconditions:
- dataLen <= ep.DataCap().
- No previous call to ep.SendRecv() or ep.RecvFirst() has returned an error.
- ep.SendLast() has never been called.
- If ep is a client Endpoint, ep.Connect() has previously been called and returned nil.
func (*Endpoint) SendRecvFast ¶
SendRecvFast is equivalent to SendRecv, but may prevent the caller's runtime P from being released, in which case the calling goroutine continues to count against GOMAXPROCS while waiting for the peer Endpoint to return control to the caller.
SendRecvFast is appropriate if the peer Endpoint is expected to consistently return control in a short amount of time (less than ~10ms).
Preconditions: As for SendRecv.
func (*Endpoint) Shutdown ¶
func (ep *Endpoint) Shutdown()
Shutdown causes concurrent and future calls to ep.Connect(), ep.SendRecv(), ep.RecvFirst(), and ep.SendLast(), as well as the same calls in the peer Endpoint, to unblock and return ShutdownErrors. It does not wait for concurrent calls to return. Successive calls to Shutdown have no effect.
Shutdown is the only Endpoint method that may be called concurrently with other methods on the same Endpoint.
type EndpointOption ¶
type EndpointOption interface {
// contains filtered or unexported methods
}
An EndpointOption configures an Endpoint.
type EndpointSide ¶
type EndpointSide int
EndpointSide indicates which side of a connection an Endpoint belongs to.
const ( // ClientSide indicates that an Endpoint is a client (initially-active; // first method call should be Connect). ClientSide EndpointSide = iota // ServerSide indicates that an Endpoint is a server (initially-inactive; // first method call should be RecvFirst.) ServerSide )
type PacketWindowAllocator ¶
type PacketWindowAllocator struct {
// contains filtered or unexported fields
}
A PacketWindowAllocator owns a shared memory file, and allocates packet windows from it.
func NewPacketWindowAllocator ¶
func NewPacketWindowAllocator() (*PacketWindowAllocator, error)
NewPacketWindowAllocator is a convenience function that returns an initialized PacketWindowAllocator allocated on the heap.
func (*PacketWindowAllocator) Allocate ¶
func (pwa *PacketWindowAllocator) Allocate(size int) (PacketWindowDescriptor, error)
Allocate allocates a new packet window of at least the given size and returns a PacketWindowDescriptor representing it.
Preconditions: size > 0.
func (*PacketWindowAllocator) Destroy ¶
func (pwa *PacketWindowAllocator) Destroy()
Destroy releases resources owned by pwa. This invalidates file descriptors previously returned by pwa.FD() and pwd.Allocate().
func (*PacketWindowAllocator) FD ¶
func (pwa *PacketWindowAllocator) FD() int
FD represents the file descriptor of the shared memory file backing pwa.
func (*PacketWindowAllocator) Init ¶
func (pwa *PacketWindowAllocator) Init() error
Init must be called on zero-value PacketWindowAllocators before first use. If it succeeds, Destroy() must be called once the PacketWindowAllocator is no longer in use.
type PacketWindowDescriptor ¶
type PacketWindowDescriptor struct {
// FD is the file descriptor representing the shared memory file.
FD int
// Offset is the offset into the shared memory file at which the packet
// window begins.
Offset int64
// Length is the size of the packet window in bytes.
Length int
}
PacketWindowDescriptor represents a packet window, a range of pages in a shared memory file that is used to exchange packets between partner Endpoints.
type ShutdownError ¶
type ShutdownError struct{}
ShutdownError is returned by most Endpoint methods after Endpoint.Shutdown() has been called.
Source Files