arpc

package module
v1.2.18 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 19, 2026 License: MIT Imports: 18 Imported by: 89

README

ARPC - More Effective Network Communication

Slack

Mentioned in Awesome Go MIT licensed Build Status Go Report Card Coverage Statusd

Contents

Features

  • Two-Way Calling
  • Two-Way Notify
  • Sync and Async Calling
  • Sync and Async Response
  • Singleflight Call De-duplication
  • Batch Write | Writev | net.Buffers
  • Broadcast
  • Middleware
  • Pub/Sub
  • Opentracing
Pattern Interactive Directions Description
call two-way:
c -> s
s -> c
request and response
notify two-way:
c -> s
s -> c
request without response

Performance

Here are some thirdparty benchmark including arpc, although these repos have provide the performance report, but I suggest you run the code yourself and get the real result, other than just believe other people's doc:

Header Layout

  • LittleEndian
bodyLen reserved cmd flag methodLen sequence method body
4 bytes 1 byte 1 byte 1 bytes 1 bytes 8 bytes methodLen bytes bodyLen-methodLen bytes

Installation

  1. Get and install arpc
$ go get -u github.com/lesismal/arpc
  1. Import in your code:
import "github.com/lesismal/arpc"

Quick Start

package main

import "github.com/lesismal/arpc"

func main() {
	server := arpc.NewServer()

	// register router
	server.Handler.Handle("/echo", func(ctx *arpc.Context) {
		str := ""
		if err := ctx.Bind(&str); err == nil {
			ctx.Write(str)
		}
	})

	server.Run("localhost:8888")
}
package main

import (
	"log"
	"net"
	"time"

	"github.com/lesismal/arpc"
)

func main() {
	client, err := arpc.NewClient(func() (net.Conn, error) {
		return net.DialTimeout("tcp", "localhost:8888", time.Second*3)
	})
	if err != nil {
		panic(err)
	}
	defer client.Stop()

	req := "hello"
	rsp := ""
	err = client.Call("/echo", &req, &rsp, time.Second*5)
	if err != nil {
		log.Fatalf("Call failed: %v", err)
	} else {
		log.Printf("Call Response: \"%v\"", rsp)
	}
}

API Examples

Register Routers
var handler arpc.Handler

// package
handler = arpc.DefaultHandler
// server
handler = server.Handler
// client
handler = client.Handler

// message would be default handled one by one  in the same conn reader goroutine
handler.Handle("/route", func(ctx *arpc.Context) { ... })
handler.Handle("/route2", func(ctx *arpc.Context) { ... })

// this make message handled by a new goroutine
async := true
handler.Handle("/asyncResponse", func(ctx *arpc.Context) { ... }, async)
Register Service Methods

Instead of registering each route by hand, handler.Register(m, svc) reflects over the struct value svc and registers all of its eligible methods at once, each under the "Service.Method" route name m + "." + <MethodName> (or just <MethodName> when m is empty). If no method is registered, Register panics.

There are two method shapes that Register recognizes:

  • The first shape(a typed request/response method): an exported method with the signature func(ctx context.Context, req *Request, rsp *Response) and no return values, where req/rsp are pointers to structs.
  • The second shape(an arpc.HandlerFunc method): an exported method of type func(*arpc.Context).

Register handles three cases, summarized here and shown in the examples below:

Case Methods on the struct Registered handler Reflection at call time? Performance
1. First shape alone Foo(ctx, req, rsp) only an auto-generated handler that news req/rsp, binds the request, calls Foo, then writes the response Yes — reflect.New + reflect.Value.Call on every request Slower
2. Second shape alone Bar(ctx *arpc.Context) only (any name, it does not have to end with Binding) the method itself No — a plain function call Fast
3. Both, paired Foo(ctx, req, rsp) + FooBinding(ctx *arpc.Context) the FooBinding method, registered under the route name Foo No — a plain function call Fast

Note: Register always uses reflection while registering(a one-time cost at startup). The table above is about the call-time / per-request path: only case 1's auto-generated handler keeps using reflection on every request, so prefer case 2 or case 3 on hot paths.

In case 3 the two methods must be paired by name: the second method is named <FirstMethodName>Binding. It is registered under the first method's name, and lets you write the binding/response logic yourself instead of relying on the reflection-based auto-generated handler.

type Echo struct{}

type EchoReq struct{ Message string }
type EchoRsp struct{ Message string }

// Case 1: first shape alone(no "HelloBinding"). Register auto-generates a
// reflection-based handler that binds the request, calls Hello and writes the
// response, registered as "Echo.Hello".
func (e *Echo) Hello(ctx context.Context, req *EchoReq, rsp *EchoRsp) {
	rsp.Message = "hello, " + req.Message
}

// Case 2: second shape alone. A plain arpc.HandlerFunc method, registered as
// "Echo.Ping". The name need not end with "Binding".
func (e *Echo) Ping(ctx *arpc.Context) {
	ctx.Write("pong")
}

// Case 3: paired. Say is the first shape, SayBinding is the second shape named
// after it. SayBinding is registered under the first method's name "Echo.Say",
// and the call path is a plain function call(no reflection).
// arpc.Context implements context.Context, so it can be passed through directly.
func (e *Echo) Say(ctx context.Context, req *EchoReq, rsp *EchoRsp) {
	rsp.Message = req.Message
}
func (e *Echo) SayBinding(ctx *arpc.Context) {
	req := &EchoReq{}
	rsp := &EchoRsp{}
	if err := ctx.Bind(req); err != nil {
		ctx.Error(err)
		return
	}
	e.Say(ctx, req, rsp)
	ctx.Write(rsp)
}

var handler arpc.Handler

// package
handler = arpc.DefaultHandler
// server
handler = server.Handler
// client
handler = client.Handler

// registers "Echo.Hello"(case 1, auto-generated), "Echo.Ping"(case 2) and
// "Echo.Say"(case 3, via SayBinding)
if err := handler.Register("Echo", &Echo{}); err != nil {
	log.Fatal(err)
}
Router Middleware

See router middleware, it's easy to implement middlewares yourself

import "github.com/lesismal/arpcex/extension/middleware/router"

var handler arpc.Handler

// package
handler = arpc.DefaultHandler
// server
handler = server.Handler
// client
handler = client.Handler

handler.Use(router.Recover())
handler.Use(router.Logger())
handler.Use(func(ctx *arpc.Context) { ... })
handler.Handle("/echo", func(ctx *arpc.Context) { ... })
handler.Use(func(ctx *arpc.Context) { ... })
Coder Middleware
  • Coder Middleware is used for converting a message data to your designed format, e.g encrypt/decrypt and compress/uncompress
import "github.com/lesismal/arpcex/extension/middleware/coder/gzip"

var handler arpc.Handler

// package
handler = arpc.DefaultHandler
// server
handler = server.Handler
// client
handler = client.Handler

handler.UseCoder(gzip.New())
handler.Handle("/echo", func(ctx *arpc.Context) { ... })
Client Call, CallAsync, Notify
  1. Call (Block, with timeout/context)
request := &Echo{...}
response := &Echo{}
timeout := time.Second*5
err := client.Call("/call/echo", request, response, timeout)
// ctx, cancel := context.WithTimeout(context.Background(), time.Second)
// defer cancel()
// err := client.CallWith(ctx, "/call/echo", request, response)
  1. CallAsync (Nonblock, with callback and timeout/context)
request := &Echo{...}

timeout := time.Second*5
err := client.CallAsync("/call/echo", request, func(ctx *arpc.Context) {
	response := &Echo{}
	ctx.Bind(response)
	...	
}, timeout)
  1. Notify (same as CallAsync with timeout/context, without callback)
data := &Notify{...}
client.Notify("/notify", data, time.Second)
// ctx, cancel := context.WithTimeout(context.Background(), time.Second)
// defer cancel()
// client.NotifyWith(ctx, "/notify", data)
Singleflight (Call De-duplication)

Enable singleflight on a router/method to de-duplicate concurrent calls: when several goroutines call the same method with the same key at the same time, only one request is actually sent to the server and all of them share its response. This cuts duplicated round-trips and server load for hot, identical requests. It applies to Call, CallContext/CallWith and CallAsync.

Only methods you register are optimized; every other method behaves exactly as before.

// Configure it on the Handler used by your Client (or use the package-level
// arpc.Singleflight(...) which applies to arpc.DefaultHandler).

// 1) Default key: req.String() when req implements fmt.Stringer,
//    otherwise fmt.Sprintf("%v", req).
handler.Singleflight("/call/echo")

// 2) Or provide a custom func that computes the de-dup key from the req.
handler.Singleflight("/user/get", func(req interface{}) string {
	return req.(*GetUserReq).ID
})

// Create the Client with that Handler, then call as usual; concurrent calls
// sharing the same key are collapsed into a single request.
client, _ := arpc.NewClient(dialer, handler)
err := client.Call("/call/echo", request, response, time.Second*5)

Notes:

  • The leader performs the real round-trip; followers wait for it and each decodes the shared response into their own rsp. The blocking path decodes the payload only once and shares the decoded value, so the shared response should be treated as read-only.
  • Every caller still honors its own timeout/context while waiting.
  • Call and CallContext de-duplicate together; CallAsync de-duplicates within its own kind and each follower's callback is invoked with the shared response (or its own timeout).
Server Call, CallAsync, Notify
  1. Get client and keep it in your application
var client *arpc.Client
server.Handler.Handle("/route", func(ctx *arpc.Context) {
	client = ctx.Client
	// release client
	client.OnDisconnected(func(c *arpc.Client){
		client = nil
	})
})

go func() {
	for {
		time.Sleep(time.Second)
		if client != nil {
			client.Call(...)
			client.CallAsync(...)
			client.Notify(...)
		}
	}
}()
  1. Then Call/CallAsync/Notify
Broadcast - Notify
var mux = sync.RWMutex{}
var clientMap = make(map[*arpc.Client]struct{})

func broadcast() {
	var svr *arpc.Server = ... 
	msg := svr.NewMessage(arpc.CmdNotify, "/broadcast", fmt.Sprintf("broadcast msg %d", i))
	mux.RLock()
	for client := range clientMap {
		client.PushMsg(msg, arpc.TimeZero)
	}
	mux.RUnlock()
}
Async Response
var handler arpc.Handler

// package
handler = arpc.DefaultHandler
// server
handler = server.Handler
// client
handler = client.Handler

asyncResponse := true // default is true, or set false
handler.Handle("/echo", func(ctx *arpc.Context) {
	req := ...
	err := ctx.Bind(req)
	if err == nil {
		ctx.Write(data)
	}
}, asyncResponse)
Handle New Connection
// package
arpc.DefaultHandler.HandleConnected(func(c *arpc.Client) {
	...
})

// server
svr := arpc.NewServer()
svr.Handler.HandleConnected(func(c *arpc.Client) {
	...
})

// client
client, err := arpc.NewClient(...)
client.Handler.HandleConnected(func(c *arpc.Client) {
	...
})
Handle Disconnected
// package
arpc.DefaultHandler.HandleDisconnected(func(c *arpc.Client) {
	...
})

// server
svr := arpc.NewServer()
svr.Handler.HandleDisconnected(func(c *arpc.Client) {
	...
})

// client
client, err := arpc.NewClient(...)
client.Handler.HandleDisconnected(func(c *arpc.Client) {
	...
})
Handle Client's reconnect

Called after every reconnect attempt of a client-role Client, whether it succeeds or not.

client, err := arpc.NewClient(...)
client.Handler.HandleReconnect(func(c *arpc.Client, info *arpc.ReconnectInfo) {
	// info.Times:    1-based attempt number in the current reconnect round
	// info.MaxTimes: Handler.MaxReconnectTimes(), <= 0 means unlimited
	// info.Addr:     remote address of the lost connection
	// info.Success:  whether the Dial succeeded
	// info.Err:      Dial error, nil on success
	...
})
Handle Client's send queue overstock
// package
arpc.DefaultHandler.HandleOverstock(func(c *arpc.Client) {
	...
})

// server
svr := arpc.NewServer()
svr.Handler.HandleOverstock(func(c *arpc.Client) {
	...
})

// client
client, err := arpc.NewClient(...)
client.Handler.HandleOverstock(func(c *arpc.Client) {
	...
})
Custom Net Protocol
// server
var ln net.Listener = ...
svr := arpc.NewServer()
svr.Serve(ln)

// client
dialer := func() (net.Conn, error) { 
	return ... 
}
client, err := arpc.NewClient(dialer)
Custom Codec
import "github.com/lesismal/arpc/codec"

var codec arpc.Codec = ...

// package
codec.Defaultcodec = codec

// server
svr := arpc.NewServer()
svr.Codec = codec

// client
client, err := arpc.NewClient(...)
client.Codec = codec
Custom Logger
import "github.com/lesismal/arpc/log"

var logger arpc.Logger = ...
log.SetLogger(logger) // log.DefaultLogger = logger
Custom operations before conn's recv and send
arpc.DefaultHandler.BeforeRecv(func(conn net.Conn) error) {
	// ...
})

arpc.DefaultHandler.BeforeSend(func(conn net.Conn) error) {
	// ...
})
Custom arpc.Client's Reader by wrapping net.Conn
arpc.DefaultHandler.SetReaderWrapper(func(conn net.Conn) io.Reader) {
	// ...
})
Custom arpc.Client's send queue capacity
arpc.DefaultHandler.SetSendQueueSize(4096)

JS Client

Web Chat Examples

Pub/Sub Examples

  • start a server
import "github.com/lesismal/arpcex/extension/pubsub"

var (
	address = "localhost:8888"

	password = "123qwe"

	topicName = "Broadcast"
)

func main() {
	s := pubsub.NewServer()
	s.Password = password

	// server publish to all clients
	go func() {
		for i := 0; true; i++ {
			time.Sleep(time.Second)
			s.Publish(topicName, fmt.Sprintf("message from server %v", i))
		}
	}()

	s.Run(address)
}
  • start a subscribe client
import "github.com/lesismal/arpc/log"
import "github.com/lesismal/arpcex/extension/pubsub"

var (
	address = "localhost:8888"

	password = "123qwe"

	topicName = "Broadcast"
)

func onTopic(topic *pubsub.Topic) {
	log.Info("[OnTopic] [%v] \"%v\", [%v]",
		topic.Name,
		string(topic.Data),
		time.Unix(topic.Timestamp/1000000000, topic.Timestamp%1000000000).Format("2006-01-02 15:04:05.000"))
}

func main() {
	client, err := pubsub.NewClient(func() (net.Conn, error) {
		return net.DialTimeout("tcp", address, time.Second*3)
	})
	if err != nil {
		panic(err)
	}
	client.Password = password

	// authentication
	err = client.Authenticate()
	if err != nil {
		panic(err)
	}

	// subscribe topic
	if err := client.Subscribe(topicName, onTopic, time.Second); err != nil {
		panic(err)
	}

	<-make(chan int)
}
  • start a publish client
import "github.com/lesismal/arpcex/extension/pubsub"

var (
	address = "localhost:8888"

	password = "123qwe"

	topicName = "Broadcast"
)

func main() {
	client, err := pubsub.NewClient(func() (net.Conn, error) {
		return net.DialTimeout("tcp", address, time.Second*3)
	})
	if err != nil {
		panic(err)
	}
	client.Password = password

	// authentication
	err = client.Authenticate()
	if err != nil {
		panic(err)
	}

	for i := 0; true; i++ {
		if i%5 == 0 {
			// publish msg to all clients
			client.Publish(topicName, fmt.Sprintf("message from client %d", i), time.Second)
		} else {
			// publish msg to only one client
			client.PublishToOne(topicName, fmt.Sprintf("message from client %d", i), time.Second)
		}
		time.Sleep(time.Second)
	}
}

More Examples

Documentation

Index

Constants

View Source
const (
	// TimeZero as a push timeout means not to wait if the send queue is full.
	TimeZero time.Duration = 0
	// TimeForever as a push timeout means to wait until the message is queued
	// or the Client stops.
	TimeForever time.Duration = 1<<63 - 1
)
View Source
const (
	// CmdNone is invalid.
	CmdNone byte = 0

	// CmdRequest is a request that expects a response.
	CmdRequest byte = 1

	// CmdResponse is a response to a request.
	CmdResponse byte = 2

	// CmdNotify is a one-way message that expects no response.
	CmdNotify byte = 3

	// CmdPing is a heartbeat; the receiver replies with CmdPong.
	CmdPing byte = 4

	// CmdPong is the reply to CmdPing.
	CmdPong byte = 5

	// CmdStream is a Stream message.
	CmdStream byte = 6
)

Message commands, stored in the low 6 bits of the Cmd byte of the header.

View Source
const (
	// HeaderIndexBodyLenBegin is where the body length begins.
	HeaderIndexBodyLenBegin = 0
	// HeaderIndexBodyLenEnd is where the body length ends.
	HeaderIndexBodyLenEnd = 4
	// HeaderIndexReserved is the index of the reserved byte.
	HeaderIndexReserved = 4
	// HeaderIndexCmd is the index of the cmd byte.
	HeaderIndexCmd = 5
	// HeaderIndexFlag is the index of the flag byte.
	HeaderIndexFlag = 6
	// HeaderIndexMethodLen is the index of the method length byte.
	HeaderIndexMethodLen = 7
	// HeaderIndexSeqBegin is where the sequence number begins.
	HeaderIndexSeqBegin = 8
	// HeaderIndexSeqEnd is where the sequence number ends.
	HeaderIndexSeqEnd = 16
	// HeaderFlagMaskError marks an error response.
	HeaderFlagMaskError byte = 0x01
	// HeaderFlagMaskAsync marks a message of an async call.
	HeaderFlagMaskAsync byte = 0x02

	// HeaderStreamLocalBitIndex is the bit index, in the cmd byte, of the flag
	// set on messages sent by the side that created the Stream.
	HeaderStreamLocalBitIndex = 7
	// HeaderStreamEOFBitIndex is the bit index, in the cmd byte, of the flag
	// set on the last message of a Stream's send half.
	HeaderStreamEOFBitIndex = 6
	// HeaderStreamLocalBit is the mask of the stream local bit.
	HeaderStreamLocalBit = byte(0x1) << HeaderStreamLocalBitIndex
	// HeaderStreamEOFBit is the mask of the stream EOF bit.
	HeaderStreamEOFBit = byte(0x1) << HeaderStreamEOFBitIndex
	// HeaderStreamFlagBitMask is the mask of all stream bits in the cmd byte.
	HeaderStreamFlagBitMask = HeaderStreamLocalBit | HeaderStreamEOFBit
	// HeaderCmdBitMask is the mask of the cmd bits in the cmd byte.
	HeaderCmdBitMask = ^HeaderStreamFlagBitMask
)

Header layout (HeadLen bytes, little endian), followed by the method name and then the payload data:

[0, 4)  body length: len(method) + len(data)
[4]     reserved byte for user flag bits, see Message.SetFlagBit
[5]     cmd in the low 6 bits, plus the stream EOF (bit 6) and local (bit 7) bits
[6]     flags: error, async
[7]     method length
[8, 16) sequence number
View Source
const (
	// HeadLen is the length of the Message header.
	HeadLen int = 16

	// MaxMethodLen is the max length of a method name.
	MaxMethodLen int = 127

	// DefaultMaxBodyLen is the default max body length (method + data) of a
	// received Message, see Handler.SetMaxBodyLen.
	DefaultMaxBodyLen int = 1024*1024*64 - 16
)

Variables

View Source
var (
	// ErrClientTimeout is returned when a call times out or its context is done.
	ErrClientTimeout = errors.New("timeout")

	// ErrClientInvalidTimeoutZero is returned when a timeout of 0 is not allowed.
	ErrClientInvalidTimeoutZero = errors.New("invalid timeout, should not be 0")

	// ErrClientInvalidTimeoutLessThanZero is returned for a negative timeout.
	ErrClientInvalidTimeoutLessThanZero = errors.New("invalid timeout, should not be < 0")

	// ErrClientInvalidTimeoutZeroWithNonNilCallback is reserved for a timeout of 0
	// with a non-nil callback. It is currently not returned by arpc.
	ErrClientInvalidTimeoutZeroWithNonNilCallback = errors.New("invalid timeout 0 with non-nil callback")

	// ErrClientOverstock is returned when the Client's send queue stays full
	// until the timeout.
	ErrClientOverstock = errors.New("timeout: rpc Client's send queue is full")

	// ErrClientReconnecting is returned when the Client is reconnecting.
	ErrClientReconnecting = errors.New("client reconnecting")

	// ErrClientStopped is returned when the Client has been stopped.
	ErrClientStopped = errors.New("client stopped")

	// ErrClientInvalidPoolDialers is returned by NewClientPoolFromDialers when
	// no dialer is given.
	ErrClientInvalidPoolDialers = errors.New("invalid dialers: empty array")

	// ErrClientInvalidAsyncHandler is returned when the async handler is nil.
	ErrClientInvalidAsyncHandler = errors.New("invalid async handler: should not be nil")
)

client errors

View Source
var (
	// ErrInvalidRspMessage is returned when a response message's Cmd is not
	// CmdResponse.
	ErrInvalidRspMessage = errors.New("invalid response message cmd")

	// ErrMethodNotFound is sent back to the caller when no handler is registered
	// for the requested method.
	ErrMethodNotFound = errors.New("method not found")

	// ErrInvalidFlagBitIndex is returned when a flag bit index is out of 0-7.
	ErrInvalidFlagBitIndex = errors.New("invalid index, should be 0-7")
)

message errors

View Source
var (
	// PingMessage is the shared heartbeat message.
	PingMessage = newMessage(CmdPing, "", nil, false, false, 0, nil, nil, nil)

	// PongMessage is the shared reply to PingMessage.
	PongMessage = newMessage(CmdPong, "", nil, false, false, 0, nil, nil, nil)
)
View Source
var (
	// ErrContextResponseToNotify is returned when writing a response to a
	// Notify message, which expects none.
	ErrContextResponseToNotify = errors.New("should not response to a context with notify message")
)

context errors

View Source
var (
	// ErrStreamClosedSend is returned when sending on a Stream whose send side
	// has been closed.
	ErrStreamClosedSend = errors.New("stream has closed send")
)

stream errors

View Source
var (
	// ErrTimeout is returned when an operation times out.
	ErrTimeout = errors.New("timeout")
)

general errors

Functions

func Append added in v1.2.7

func Append(buf []byte, more ...byte) []byte

Append calls DefaultAllocator.Append.

func AppendString added in v1.2.7

func AppendString(buf []byte, more string) []byte

AppendString calls DefaultAllocator.AppendString.

func AsyncExecute added in v1.1.10

func AsyncExecute(f func())

AsyncExecute calls DefaultHandler.AsyncExecute.

func AsyncResponse

func AsyncResponse() bool

AsyncResponse calls DefaultHandler.AsyncResponse.

func BatchRecv

func BatchRecv() bool

BatchRecv calls DefaultHandler.BatchRecv.

func BatchSend

func BatchSend() bool

BatchSend calls DefaultHandler.BatchSend.

func BeforeRecv

func BeforeRecv(h func(net.Conn) error)

BeforeRecv calls DefaultHandler.BeforeRecv.

func BeforeSend

func BeforeSend(h func(net.Conn) error)

BeforeSend calls DefaultHandler.BeforeSend.

func EnablePool added in v1.1.9

func EnablePool(enable bool)

EnablePool calls DefaultHandler.EnablePool.

func Free added in v1.1.9

func Free(buf []byte)

Free calls DefaultAllocator.Free.

func Handle

func Handle(m string, h HandlerFunc, args ...interface{})

Handle calls DefaultHandler.Handle.

func HandleConnected

func HandleConnected(onConnected func(*Client))

HandleConnected calls DefaultHandler.HandleConnected.

func HandleDisconnected

func HandleDisconnected(onDisConnected func(*Client))

HandleDisconnected calls DefaultHandler.HandleDisconnected.

func HandleFree added in v1.2.17

func HandleFree(f func([]byte))

HandleFree calls DefaultHandler.HandleFree.

func HandleMalloc added in v1.1.9

func HandleMalloc(f func(int) []byte)

HandleMalloc calls DefaultHandler.HandleMalloc.

func HandleMessageDropped

func HandleMessageDropped(onOverstock func(c *Client, m *Message))

HandleMessageDropped calls DefaultHandler.HandleMessageDropped.

func HandleNotFound

func HandleNotFound(h HandlerFunc)

HandleNotFound calls DefaultHandler.HandleNotFound.

func HandleOverstock

func HandleOverstock(onOverstock func(c *Client, m *Message))

HandleOverstock calls DefaultHandler.HandleOverstock.

func HandleReconnect added in v1.2.18

func HandleReconnect(onReconnect func(c *Client, info *ReconnectInfo))

HandleReconnect calls DefaultHandler.HandleReconnect.

func HandleSessionMiss

func HandleSessionMiss(onSessionMiss func(c *Client, m *Message))

HandleSessionMiss calls DefaultHandler.HandleSessionMiss.

func LogDebugInfo added in v1.2.7

func LogDebugInfo()

LogDebugInfo calls LogDebugInfo of DefaultAllocator if it is a *BufferPool.

func Malloc added in v1.1.9

func Malloc(size int) []byte

Malloc calls DefaultAllocator.Malloc.

func MaxBodyLen

func MaxBodyLen() int

MaxBodyLen calls DefaultHandler.MaxBodyLen.

func ReadTimeout added in v1.2.11

func ReadTimeout() time.Duration

ReadTimeout calls DefaultHandler.ReadTimeout.

func Realloc added in v1.1.9

func Realloc(buf []byte, size int) []byte

Realloc calls DefaultAllocator.Realloc.

func RecvBufferSize

func RecvBufferSize() int

RecvBufferSize calls DefaultHandler.RecvBufferSize.

func Register added in v1.2.18

func Register(m string, h interface{}) error

Register calls DefaultHandler.Register.

func SendBufferSize added in v1.1.9

func SendBufferSize() int

SendBufferSize calls DefaultHandler.SendBufferSize.

func SendQueueSize

func SendQueueSize() int

SendQueueSize calls DefaultHandler.SendQueueSize.

func SetAsyncExecutor added in v1.1.10

func SetAsyncExecutor(executor func(f func()))

SetAsyncExecutor calls DefaultHandler.SetAsyncExecutor.

func SetAsyncResponse

func SetAsyncResponse(async bool)

SetAsyncResponse calls DefaultHandler.SetAsyncResponse.

func SetBatchRecv

func SetBatchRecv(batch bool)

SetBatchRecv calls DefaultHandler.SetBatchRecv.

func SetBatchSend

func SetBatchSend(batch bool)

SetBatchSend calls DefaultHandler.SetBatchSend.

func SetDebug added in v1.2.7

func SetDebug(enable bool)

SetDebug sets Debug of DefaultAllocator if it is a *BufferPool.

func SetHandler

func SetHandler(h Handler)

SetHandler replaces DefaultHandler.

func SetLogTag

func SetLogTag(tag string)

SetLogTag sets DefaultHandler's log tag.

func SetMaxBodyLen added in v1.1.11

func SetMaxBodyLen(l int)

SetMaxBodyLen calls DefaultHandler.SetMaxBodyLen.

func SetReadTimeout added in v1.2.11

func SetReadTimeout(timeout time.Duration)

SetReadTimeout calls DefaultHandler.SetReadTimeout.

func SetReaderWrapper

func SetReaderWrapper(wrapper func(conn net.Conn) io.Reader)

SetReaderWrapper calls DefaultHandler.SetReaderWrapper.

func SetRecvBufferSize

func SetRecvBufferSize(size int)

SetRecvBufferSize calls DefaultHandler.SetRecvBufferSize.

func SetSendBufferSize added in v1.1.9

func SetSendBufferSize(size int)

SetSendBufferSize calls DefaultHandler.SetSendBufferSize.

func SetSendQueueSize

func SetSendQueueSize(size int)

SetSendQueueSize calls DefaultHandler.SetSendQueueSize.

func SetStreamQueueSize added in v1.2.15

func SetStreamQueueSize(size int)

SetStreamQueueSize calls DefaultHandler.SetStreamQueueSize.

func SetWriteTimeout added in v1.2.11

func SetWriteTimeout(timeout time.Duration)

SetWriteTimeout calls DefaultHandler.SetWriteTimeout.

func Singleflight added in v1.2.18

func Singleflight(method string, keyFunc ...func(req interface{}) string)

Singleflight calls DefaultHandler.Singleflight.

func StreamQueueSize added in v1.2.15

func StreamQueueSize() int

StreamQueueSize calls DefaultHandler.StreamQueueSize.

func Use

func Use(h HandlerFunc)

Use calls DefaultHandler.Use.

func UseCoder

func UseCoder(coder MessageCoder)

UseCoder calls DefaultHandler.UseCoder.

func WriteTimeout added in v1.2.11

func WriteTimeout() time.Duration

WriteTimeout calls DefaultHandler.WriteTimeout.

Types

type Allocator added in v1.2.7

type Allocator interface {
	// Malloc returns a buffer of length size.
	Malloc(size int) []byte
	// Realloc resizes buf to size, keeping its content. The result may be a
	// new buffer, in which case buf must not be used any more.
	Realloc(buf []byte, size int) []byte
	// Append appends more to buf, like the builtin append.
	Append(buf []byte, more ...byte) []byte
	// AppendString appends more to buf, like the builtin append.
	AppendString(buf []byte, more string) []byte
	// Free recycles buf, which must not be used after that.
	Free(buf []byte)
}

Allocator allocates and recycles byte buffers.

var DefaultAllocator Allocator = New(64, 64)

DefaultAllocator is the package-level Allocator: a BufferPool with a single pool of 64-byte-initial buffers.

func New added in v1.1.9

func New(smallSize, bigSize int) Allocator

New creates a BufferPool. Buffers with a size >= bigSize come from the big pool, others from the small pool. smallSize defaults to 64, bigSize to 64KB, and bigSize is at least smallSize; if they are equal, one pool is used.

type AsyncHandlerFunc added in v1.2.12

type AsyncHandlerFunc func(*Context, error)

AsyncHandlerFunc is the callback of Client.CallAsync. On success, ctx holds the response and err is the remote error, if any; on timeout or disconnect, ctx is nil and err is ErrTimeout or ErrClientReconnecting.

type BufferPool added in v1.1.9

type BufferPool struct {
	// Debug enables leak tracking: the stack of each Malloc is recorded until
	// the buffer is freed, and freeing an untracked buffer panics.
	Debug bool
	// contains filtered or unexported fields
}

BufferPool is an Allocator backed by two sync.Pools: one for buffers smaller than bigSize and one for the others. Buffers grow as needed and are reused with their grown capacity.

func (*BufferPool) Append added in v1.2.7

func (bp *BufferPool) Append(buf []byte, more ...byte) []byte

Append appends more to buf, see AppendString.

func (*BufferPool) AppendString added in v1.2.7

func (bp *BufferPool) AppendString(buf []byte, more string) []byte

AppendString appends more to buf. When the length grows from below bigSize to bigSize or more, the result moves to a buffer from the big pool and buf is freed.

func (*BufferPool) Free added in v1.2.7

func (bp *BufferPool) Free(buf []byte)

Free puts buf back to the pool chosen by its capacity.

func (*BufferPool) LogDebugInfo added in v1.2.7

func (bp *BufferPool) LogDebugInfo()

LogDebugInfo prints the stacks of the buffers not freed yet and the alloc/free counts to stdout. Only meaningful with Debug enabled.

func (*BufferPool) Malloc added in v1.2.7

func (bp *BufferPool) Malloc(size int) []byte

Malloc returns a pooled buffer of length size, growing it if its capacity is not enough.

func (*BufferPool) Realloc added in v1.2.7

func (bp *BufferPool) Realloc(buf []byte, size int) []byte

Realloc resizes buf to size. When buf grows from below bigSize to bigSize or more, it moves to a buffer from the big pool and the old one is freed.

type Client

type Client struct {

	// Conn is the current conn; it changes on reconnect and Restart.
	Conn net.Conn
	// Codec encodes and decodes message bodies.
	Codec codec.Codec
	// Handler handles the Client's messages and events.
	Handler Handler
	// Reader reads from Conn, wrapped by Handler.WrapReader with BatchRecv.
	Reader io.Reader
	// Dialer dials the server; nil for a server-role Client.
	Dialer DialerFunc
	// Head is the buffer for reading the body length of each message.
	Head Header
	// contains filtered or unexported fields
}

Client is one arpc connection, on either side: a client-role Client dials the server (see NewClient) and reconnects when the conn breaks, while a server-role Client is created by a Server for each accepted conn. Both can make calls to and serve calls from the peer.

A Client is safe for concurrent use; there may be multiple outstanding calls at a time.

func NewClient

func NewClient(dialer DialerFunc, args ...interface{}) (*Client, error)

NewClient dials with dialer and starts a client-role Client on the conn. args[0], if it is a Handler, is used as is; otherwise the Client uses a clone of DefaultHandler. The Codec is codec.DefaultCodec.

func (*Client) Call

func (c *Client) Call(method string, req interface{}, rsp interface{}, timeout time.Duration, args ...interface{}) error

Call sends a request for method with req and waits for the response, decoding it into rsp. timeout must be > 0 and covers both queuing and waiting. args[0], if any, must be a map[interface{}]interface{} of message values.

req and rsp may be []byte, string or pointers to them, or values handled by the Client's Codec; see util.ValueToBytes. It returns ErrClientTimeout on timeout, or the remote error for an error response.

func (*Client) CallAsync

func (c *Client) CallAsync(method string, req interface{}, handler AsyncHandlerFunc, timeout time.Duration, args ...interface{}) error

CallAsync sends a request for method with req and returns without waiting for the response. handler must not be nil and timeout must be > 0. handler is called at most once: with the response, with ErrTimeout if none arrives within timeout, or with ErrClientReconnecting if the conn breaks. It is not called if CallAsync returns an error or the request is dropped unsent.

func (*Client) CallContext added in v1.2.12

func (c *Client) CallContext(ctx context.Context, method string, req interface{}, rsp interface{}, args ...interface{}) error

CallContext is like Call, but waits until ctx is done instead of a timeout.

func (*Client) CallWith

func (c *Client) CallWith(ctx context.Context, method string, req interface{}, rsp interface{}, args ...interface{}) error

CallWith uses context to make rpc call. CallWith blocks to wait for a response from the server until it times out.

func (*Client) CheckState

func (c *Client) CheckState() error

CheckState returns ErrClientStopped if the Client is not running, ErrClientReconnecting if it is reconnecting, or nil.

func (*Client) Delete

func (c *Client) Delete(key interface{})

Delete deletes the value for key.

func (*Client) Get

func (c *Client) Get(key interface{}) (interface{}, bool)

Get returns the value stored on the Client for key. Values are local and cleared by Restart.

func (*Client) IsClient added in v1.2.18

func (c *Client) IsClient() bool

IsClient reports whether c is a client-role Client, i.e. it has a Dialer.

func (*Client) IsServer added in v1.2.18

func (c *Client) IsServer() bool

IsServer reports whether c is a server-role Client, i.e. it has no Dialer.

func (*Client) Keepalive added in v1.2.11

func (c *Client) Keepalive(interval time.Duration)

Keepalive sends a Ping every interval (30s if interval <= 0) while the Client is running. It returns immediately.

func (*Client) NewMessage

func (c *Client) NewMessage(cmd byte, method string, v interface{}, args ...interface{}) *Message

NewMessage creates a Message with a new sequence number and the Client's Handler and Codec. args[0], if any, must be a map[interface{}]interface{} of message values.

func (*Client) NewStream added in v1.2.15

func (client *Client) NewStream(method string) *Stream

NewStream creates a local Stream for method. The peer's handler for method, registered by Handler.HandleStream, is called on its first message.

func (*Client) Notify

func (c *Client) Notify(method string, data interface{}, timeout time.Duration, args ...interface{}) error

Notify sends a notify for method with data; the peer sends no response. With AsyncWrite, timeout bounds waiting for the send queue, and 0 means not to wait (ErrClientOverstock if full); it must not be negative. args[0], if any, must be a map[interface{}]interface{} of message values.

func (*Client) NotifyContext added in v1.2.12

func (c *Client) NotifyContext(ctx context.Context, method string, data interface{}, args ...interface{}) error

NotifyContext is like Notify, but waits for the send queue until ctx is done instead of a timeout.

func (*Client) NotifyWith

func (c *Client) NotifyWith(ctx context.Context, method string, data interface{}, args ...interface{}) error

NotifyWith is an alias of NotifyContext.

func (*Client) Ping added in v1.2.11

func (c *Client) Ping()

Ping writes a ping message directly to the conn, bypassing the send queue.

func (*Client) Pong added in v1.2.11

func (c *Client) Pong()

Pong writes a pong message directly to the conn, bypassing the send queue.

func (*Client) PushMsg

func (c *Client) PushMsg(msg *Message, timeout time.Duration) error

PushMsg sends msg as is. With AsyncWrite, timeout bounds waiting for the send queue: TimeZero means not to wait (ErrClientOverstock if full), and TimeForever or a negative value means to wait until queued or stopped. msg is passed to OnMessageDone or OnOverstock if it cannot be sent.

func (*Client) Restart

func (c *Client) Restart() error

Restart stops the Client, dials a new conn, and starts it again with fresh state: pending calls, Streams and values are dropped. It returns the Dialer's error if dialing fails. It is only for client-role Clients.

func (*Client) Set

func (c *Client) Set(key interface{}, value interface{})

Set stores a key-value pair on the Client. It does nothing if key or value is nil.

func (*Client) SetState added in v1.2.7

func (c *Client) SetState(running bool)

SetState sets the running state directly. It is only meant for Clients driven by an external non-blocking conn framework.

func (*Client) Stop

func (c *Client) Stop()

Stop stops the Client and closes its conn; a client-role Client does not reconnect after it. OnDisconnected is called by the read goroutine once it exits.

type ClientPool

type ClientPool struct {
	// contains filtered or unexported fields
}

ClientPool is a fixed set of client-role Clients.

func NewClientPool

func NewClientPool(dialer DialerFunc, size int, args ...interface{}) (*ClientPool, error)

NewClientPool creates a ClientPool of size Clients dialed with dialer and sharing one Handler: args[0] if it is a Handler, or else a clone of DefaultHandler. If any dial fails, the created Clients are stopped and the error is returned.

func NewClientPoolFromDialers

func NewClientPoolFromDialers(dialers []DialerFunc, args ...interface{}) (*ClientPool, error)

NewClientPoolFromDialers is like NewClientPool, with one Client per dialer. It returns ErrClientInvalidPoolDialers if dialers is empty.

func (*ClientPool) Get

func (pool *ClientPool) Get(index int) *Client

Get returns the Client at index, modulo the pool size.

func (*ClientPool) Handler

func (pool *ClientPool) Handler() Handler

Handler returns the Handler of the next Client, which all Clients share when the pool is created with one Handler.

func (*ClientPool) Next

func (pool *ClientPool) Next() *Client

Next returns the next Client in round robin, skipping the ones stopped or reconnecting. If all of them are, it returns the last one tried.

func (*ClientPool) Size

func (pool *ClientPool) Size() int

Size returns the number of Clients.

func (*ClientPool) Stop

func (pool *ClientPool) Stop()

Stop stops all Clients.

type Context

type Context struct {
	// Client is the connection the Message was received from.
	Client *Client
	// Message is the incoming Message.
	Message *Message
	// contains filtered or unexported fields
}

Context carries an incoming Message and the Client it came from through the middleware and handler chain. It also implements context.Context, though it never expires or gets canceled.

Contexts are taken from a pool, but only go back to it via Release, which is usually called from the Handler.HandleContextDone callback.

func (*Context) Abort added in v1.1.0

func (ctx *Context) Abort()

Abort stops the rest of the handler chain from being called.

func (*Context) Bind

func (ctx *Context) Bind(v interface{}) error

Bind decodes the Message body into v. If the Message is an error response, it returns that error instead.

*[]byte is set to the body without copying, so it is only valid until the Message is released; *string gets a copy; other types are decoded by the Client's Codec.

func (*Context) Body

func (ctx *Context) Body() []byte

Body returns the Message body.

func (*Context) Deadline added in v1.1.0

func (ctx *Context) Deadline() (deadline time.Time, ok bool)

Deadline implements context.Context. It never has a deadline.

func (*Context) Done

func (ctx *Context) Done() <-chan struct{}

Done implements context.Context. It returns nil: the Context is never canceled.

func (*Context) Err added in v1.1.0

func (ctx *Context) Err() error

Err implements context.Context. It always returns nil.

func (*Context) Error

func (ctx *Context) Error(v interface{}) error

Error sends v as an error response to the request. If v is nil, a normal response with an empty body is sent.

func (*Context) Get

func (ctx *Context) Get(key interface{}) (interface{}, bool)

Get returns the value stored in the Message's values for key.

func (*Context) Next

func (ctx *Context) Next()

Next runs the rest of the handler chain. The chain continues on its own after each middleware returns, so a middleware only needs to call Next to run code after the rest of the chain, e.g. to measure the handling time.

func (*Context) Release added in v1.1.9

func (ctx *Context) Release()

Release releases the Message and puts the Context back to the pool. The Context must not be used after that.

func (*Context) ResponseError added in v1.2.16

func (ctx *Context) ResponseError() interface{}

ResponseError returns the error value written by Error, or by Write with an error value. It is only recorded when the Handler uses AsyncWrite, and is nil otherwise.

func (*Context) Set

func (ctx *Context) Set(key interface{}, value interface{})

Set stores a key-value pair in the Message's values. It does nothing if key or value is nil.

func (*Context) Value added in v1.1.0

func (ctx *Context) Value(key interface{}) interface{}

Value implements context.Context by returning Get(key).

func (*Context) Values

func (ctx *Context) Values() map[interface{}]interface{}

Values returns the Message's values, or nil if there is no Message.

func (*Context) Write

func (ctx *Context) Write(v interface{}) error

Write sends v as the response to the request. If v is an error, the response is an error response. It returns ErrContextResponseToNotify if the incoming Message is not a request.

func (*Context) WriteWithTimeout

func (ctx *Context) WriteWithTimeout(v interface{}, timeout time.Duration) error

WriteWithTimeout is like Write, with a timeout for pushing the response into the send queue. The timeout only applies when the Handler uses AsyncWrite.

type DialerFunc

type DialerFunc func() (net.Conn, error)

DialerFunc dials the server. A client-role Client also calls it to reconnect and restart.

type Handler

type Handler interface {
	// Clone returns a copy of the Handler with its own middlewares, coders,
	// routes and context. Callbacks are shared.
	Clone() Handler

	// LogTag returns the prefix of the Handler's log lines.
	LogTag() string
	// SetLogTag sets the prefix of the Handler's log lines.
	SetLogTag(tag string)

	// HandleConnected registers the callback called when a connection is
	// established: after accept for a server-role Client, and after the first
	// connect and each successful reconnect for a client-role Client. It
	// replaces the default callback, which disables TCP_NODELAY.
	HandleConnected(onConnected func(*Client))
	// OnConnected calls the connected callback.
	OnConnected(c *Client)

	// HandleDisconnected registers the callback called when a Client stops:
	// when the conn of a server-role Client breaks, or when a client-role
	// Client gives up reconnecting or is stopped. It is not called for each
	// disconnection that is followed by a reconnect.
	HandleDisconnected(onDisConnected func(*Client))
	// OnDisconnected calls the disconnected callback.
	OnDisconnected(c *Client)

	// HandleReconnect registers the callback called after every reconnect
	// attempt of a client-role Client, whether it succeeds or not. It runs on
	// the Client's read goroutine; on success, before OnConnected.
	HandleReconnect(onReconnect func(c *Client, info *ReconnectInfo))
	// OnReconnect calls the reconnect callback.
	OnReconnect(c *Client, info *ReconnectInfo)

	// MaxReconnectTimes returns the max reconnect attempts after a client-role
	// Client loses its conn; <= 0 means unlimited.
	MaxReconnectTimes() int
	// SetMaxReconnectTimes sets the max reconnect attempts; <= 0 (default)
	// means unlimited. Attempts are 1 second apart.
	SetMaxReconnectTimes(n int)

	// HandleOverstock registers the callback called when a message cannot be
	// pushed because the send queue is full. OnMessageDone is called on the
	// message after it.
	HandleOverstock(onOverstock func(c *Client, m *Message))
	// OnOverstock calls the overstock callback. Without one registered, it
	// does nothing, not even OnMessageDone.
	OnOverstock(c *Client, m *Message)

	// HandleMessageDone registers the callback called when arpc is done with a
	// message: sent, dropped, or received and consumed. EnablePool(true) sets
	// it to release the message.
	HandleMessageDone(onMessageDone func(c *Client, m *Message))
	// OnMessageDone calls the message done callback if m is not nil.
	OnMessageDone(c *Client, m *Message)

	// HandleMessageDropped registers the callback called when a message is
	// dropped instead of being sent, e.g. while reconnecting or after the
	// Client stops. OnMessageDone is called on the message after it.
	HandleMessageDropped(onMessageDropped func(c *Client, m *Message))
	// OnMessageDropped calls the message dropped callback. Without one
	// registered, it does nothing, not even OnMessageDone.
	OnMessageDropped(c *Client, m *Message)

	// HandleSessionMiss registers the callback called when a response arrives
	// but its call is gone, e.g. timed out. OnMessageDone is called on the
	// message after it.
	HandleSessionMiss(onSessionMiss func(c *Client, m *Message))
	// OnSessionMiss calls the session miss callback. Without one registered,
	// it does nothing, not even OnMessageDone.
	OnSessionMiss(c *Client, m *Message)

	// HandleContextDone registers the callback called after the handler chain
	// of a request or notify returns, or after a CallAsync handler returns.
	// EnablePool(true) sets it to release the Context.
	HandleContextDone(onContextDone func(ctx *Context))
	// OnContextDone calls the context done callback.
	OnContextDone(ctx *Context)

	// BeforeRecv registers a hook called on the conn before reading each
	// message. A non-nil error fails the read and breaks the conn.
	BeforeRecv(h func(net.Conn) error)
	// BeforeSend registers a hook called on the conn before each write. A
	// non-nil error fails the write.
	BeforeSend(h func(net.Conn) error)

	// BatchRecv reports whether reads go through WrapReader, a buffered
	// reader by default. Default true.
	BatchRecv() bool
	// SetBatchRecv sets whether reads go through WrapReader.
	SetBatchRecv(batch bool)
	// BatchSend reports whether the send loop merges queued messages into one
	// write, up to SendBufferSize bytes. Default true, but it has no effect
	// while SendBufferSize is 0. Only used with AsyncWrite.
	BatchSend() bool
	// SetBatchSend sets whether the send loop merges queued messages.
	SetBatchSend(batch bool)

	// AsyncWrite reports whether messages are queued and written by a send
	// goroutine per Client, instead of written on the calling goroutine.
	// Default true.
	AsyncWrite() bool
	// SetAsyncWrite sets whether messages are written asynchronously.
	SetAsyncWrite(async bool)

	// AsyncWritev reports whether messages are queued and written with writev
	// (net.Buffers) by an on-demand writer goroutine, one at most per Client.
	// It takes precedence over AsyncWrite, and pushing never blocks since the
	// queue is unbounded. Default false.
	AsyncWritev() bool
	// SetAsyncWritev sets whether the writev path is used.
	SetAsyncWritev(async bool)

	// AsyncResponse reports whether handlers registered by Handle and
	// HandleStream run via AsyncExecute by default, instead of on the Client's
	// read goroutine. Default true.
	AsyncResponse() bool
	// SetAsyncResponse sets the default of AsyncResponse for handlers
	// registered after it.
	SetAsyncResponse(async bool)

	// WrapReader returns the reader used to read from conn when BatchRecv is
	// enabled. By default it is a bufio.Reader of RecvBufferSize.
	WrapReader(conn net.Conn) io.Reader
	// SetReaderWrapper replaces the WrapReader function.
	SetReaderWrapper(wrapper func(conn net.Conn) io.Reader)

	// Recv reads a message from the Client's Reader, applying BeforeRecv and
	// ReadTimeout.
	Recv(c *Client) (*Message, error)
	// Send writes buffer to conn, applying BeforeSend and WriteTimeout.
	Send(c net.Conn, buffer []byte) (int, error)
	// SendN writes buffers to conn in one writev, applying BeforeSend and
	// WriteTimeout.
	SendN(conn net.Conn, buffers net.Buffers) (int, error)

	// RecvBufferSize returns the buffer size of the default WrapReader.
	RecvBufferSize() int
	// SetRecvBufferSize sets the buffer size of the default WrapReader.
	// Default 8192.
	SetRecvBufferSize(size int)

	// SendBufferSize returns the max bytes BatchSend merges into one write.
	SendBufferSize() int
	// SetSendBufferSize sets the max bytes BatchSend merges into one write.
	// Default 0, which disables merging.
	SetSendBufferSize(size int)

	// ReadTimeout returns the read deadline set before reading each message;
	// 0 means none.
	ReadTimeout() time.Duration
	// SetReadTimeout sets the read deadline set before reading each message.
	SetReadTimeout(timeout time.Duration)

	// WriteTimeout returns the write deadline set before each write; 0 means
	// none.
	WriteTimeout() time.Duration
	// SetWriteTimeout sets the write deadline set before each write.
	SetWriteTimeout(timeout time.Duration)

	// SendQueueSize returns the capacity of each Client's send queue used by
	// AsyncWrite.
	SendQueueSize() int
	// SetSendQueueSize sets the capacity of the send queue of Clients created
	// or restarted after it. Default 4096.
	SetSendQueueSize(size int)

	// StreamQueueSize returns the capacity of each Stream's receive queue.
	StreamQueueSize() int
	// SetStreamQueueSize sets the capacity of each Stream's receive queue.
	// Default 4.
	SetStreamQueueSize(size int)

	// MaxBodyLen returns the max body length of a received message.
	MaxBodyLen() int
	// SetMaxBodyLen sets the max body length of a received message; a longer
	// one breaks the conn. Default DefaultMaxBodyLen.
	SetMaxBodyLen(l int)

	// Use appends a middleware to the handler chain of all methods, including
	// those already registered; for them it runs after their handler. The
	// chain continues after the middleware returns, unless it calls
	// Context.Abort. Stream handlers are not affected.
	Use(h HandlerFunc)

	// UseCoder appends a MessageCoder. Encode is called in registration order
	// before a message is sent, Decode in reverse order after one is received.
	UseCoder(coder MessageCoder)

	// Coders returns the registered MessageCoders.
	Coders() []MessageCoder

	// Handle registers the handler of a method, after the middlewares
	// registered so far. It panics if method is empty (use HandleNotFound),
	// too long, or already registered.
	//
	// An optional bool arg sets whether h runs via AsyncExecute (true) or on
	// the Client's read goroutine (false), overriding AsyncResponse.
	Handle(m string, h HandlerFunc, args ...interface{})

	// Singleflight enables singleflight de-duplication of Client.Call,
	// CallContext and CallAsync for method: concurrent calls with the same key
	// send only one request and share its response.
	//
	// keyFunc is optional and computes the key from the call's req. If it is
	// omitted or nil, the key is req.String() when req implements
	// fmt.Stringer, otherwise fmt.Sprintf("%v", req).
	Singleflight(method string, keyFunc ...func(req interface{}) string)

	// SingleflightKey reports whether method has singleflight enabled and, if
	// so, returns the key computed from req.
	SingleflightKey(method string, req interface{}) (string, bool)

	// Register registers the eligible methods of h as handlers, with route
	// names in the "Service.Method" form: m + "." + the method name, or just
	// the method name when m is empty.
	//
	// Eligible methods are exported and are either:
	//   - A method with the signature
	//       func(ctx context.Context, req *Request, rsp *Response)
	//     where Request and Response are structs. If h also has a method named
	//     after it plus "Binding" of HandlerFunc type, that method is
	//     registered for the route, and is expected to create req/rsp and call
	//     the first one. Otherwise an auto-generated handler is registered: it
	//     creates req/rsp, binds the request into req, calls the method with
	//     the Context, and writes rsp as the response.
	//   - A method of HandlerFunc type (func(*arpc.Context)) that is not the
	//     "Binding" method of the above.
	//
	// It panics if no method is eligible, or on any error of Handle; the
	// returned error is only non-nil for a nil h.
	Register(m string, h interface{}) error

	// HandleNotFound registers the handler for methods that have no handler.
	// By default, such requests get an ErrMethodNotFound error response.
	HandleNotFound(h HandlerFunc)

	// HandleStream registers the handler of a stream method. It is called
	// when the peer sends the first message of a new Stream for the method.
	// An optional bool arg overrides AsyncResponse, as for Handle.
	HandleStream(m string, h StreamHandlerFunc, args ...interface{})

	// OnMessage dispatches a received message: it answers pings, decodes the
	// message with the coders, then runs the handler chain for requests and
	// notifies, completes the matching call for responses, or feeds the
	// matching Stream for stream messages.
	OnMessage(c *Client, m *Message)

	// Malloc allocates a message buffer, with make by default.
	Malloc(size int) []byte
	// HandleMalloc replaces the Malloc function.
	HandleMalloc(f func(size int) []byte)

	// Append appends more to b, with the builtin append by default.
	Append(b []byte, more ...byte) []byte
	// HandleAppend replaces the Append function.
	HandleAppend(f func(b []byte, more ...byte) []byte)

	// Free recycles a buffer from Malloc; it does nothing by default.
	Free([]byte)
	// HandleFree replaces the Free function.
	HandleFree(f func(buf []byte))

	// EnablePool(true) allocates buffers from DefaultAllocator, and releases
	// Contexts and Messages when done (via HandleContextDone and
	// HandleMessageDone), so they must not be used after their handler
	// returns; use Message.Retain to keep a Message longer. EnablePool(false)
	// restores plain allocation and replaces those callbacks with no-ops.
	EnablePool(enable bool)

	// Context returns the Handler's context and its cancel func. It is not
	// used by arpc itself; Clone creates a new one.
	Context() (context.Context, context.CancelFunc)
	// SetContext replaces the Handler's context and cancel func.
	SetContext(ctx context.Context, cancel context.CancelFunc)
	// Cancel cancels the Handler's context.
	Cancel()

	// NewMessage creates a Message with this Handler, like the package-level
	// NewMessage: isError and isAsync are ignored.
	NewMessage(cmd byte, method string, v interface{}, isError bool, isAsync bool, seq uint64, codec codec.Codec, values map[interface{}]interface{}) *Message

	// NewMessageWithBuffer wraps buffer, a complete encoded message, in a
	// pooled Message. With EnablePool(true), buffer should come from Malloc
	// since it is freed when the Message is released.
	NewMessageWithBuffer(buffer []byte) *Message

	// SetAsyncExecutor sets the function AsyncExecute runs tasks with, e.g. a
	// goroutine pool.
	SetAsyncExecutor(executor func(f func()))
	// AsyncExecute runs f with the executor, or in a new goroutine with panic
	// recovery if none is set.
	AsyncExecute(f func())
}

Handler holds the configuration, callbacks and routes shared by Clients, and implements how messages are read, written and dispatched.

A Handler is not safe for concurrent modification: configure it before it is used by any Client or Server.

var DefaultHandler Handler = NewHandler()

DefaultHandler is the Handler cloned by NewServer and NewClient when none is given, and configured by the package-level functions.

func NewHandler

func NewHandler() Handler

NewHandler returns a Handler with the default settings: BatchRecv, BatchSend, AsyncWrite and AsyncResponse enabled, an 8KB recv buffer, a send queue of 4096, a stream queue of 4, and a connected callback disabling TCP_NODELAY.

type HandlerFunc

type HandlerFunc func(*Context)

HandlerFunc handles a request or notify, as a method handler or middleware.

type Header []byte

Header is the first HeaderIndexBodyLenEnd bytes of a Message read from the conn, i.e. the body length.

func (Header) BodyLen

func (h Header) BodyLen() int

BodyLen returns the body length.

type Message

type Message struct {
	Buffer []byte
	// contains filtered or unexported fields
}

Message is an arpc message: the header, the method name and the payload data, laid out contiguously in Buffer.

Messages are pooled and reference counted: the count starts at 0, Retain increments it and Release decrements it; the Message is freed when it drops below 0, so each Retain needs one extra Release.

func NewMessage added in v1.1.9

func NewMessage(cmd byte, method string, v interface{}, isError bool, isAsync bool, seq uint64, h Handler, codec codec.Codec, values map[interface{}]interface{}) *Message

NewMessage creates a Message from the pool, with v converted by util.ValueToBytes. A nil h means DefaultHandler.

Note: isError and isAsync are ignored, both flags are left unset; use SetError and SetAsync instead.

func (*Message) BodyLen

func (m *Message) BodyLen() int

BodyLen returns the body length (method + data) in the header.

func (*Message) Cmd

func (m *Message) Cmd() byte

Cmd returns the cmd, without the stream bits.

func (*Message) Data

func (m *Message) Data() []byte

Data returns the payload data after the method name, without copying.

func (*Message) Error

func (m *Message) Error() error

Error returns the data as an error if the error flag is set, otherwise nil.

func (*Message) Get

func (m *Message) Get(key interface{}) (interface{}, bool)

Get returns the value stored for key.

func (*Message) IsAsync

func (m *Message) IsAsync() bool

IsAsync reports whether the async flag is set.

func (*Message) IsError

func (m *Message) IsError() bool

IsError reports whether the error flag is set.

func (*Message) IsFlagBitSet

func (m *Message) IsFlagBitSet(index int) bool

IsFlagBitSet reports whether bit index of the reserved byte is set. It returns false for an index out of 0-7.

func (*Message) IsStreamEOF added in v1.2.15

func (m *Message) IsStreamEOF() bool

IsStreamEOF reports whether this is the last message from the sender's send half of the Stream.

func (*Message) IsStreamLocal added in v1.2.15

func (m *Message) IsStreamLocal() bool

IsStreamLocal reports whether the stream local bit is set, i.e. the message was sent by the side that created the Stream.

func (*Message) Len

func (m *Message) Len() int

Len returns the length of Buffer.

func (*Message) Method

func (m *Message) Method() string

Method returns a copy of the method name.

func (*Message) MethodLen

func (m *Message) MethodLen() int

MethodLen returns the method length.

func (*Message) Payback added in v1.1.9

func (m *Message) Payback()

Payback puts the Message back to the pool without freeing its buffers, regardless of the reference count.

func (*Message) Release added in v1.1.9

func (m *Message) Release() int32

Release decrements the reference count and returns the new value. When it reaches -1, the buffers are freed by Handler.Free and the Message goes back to the pool.

func (*Message) ResetAttrs added in v1.1.9

func (m *Message) ResetAttrs()

ResetAttrs zeroes the reserved, cmd, flag and method length bytes.

func (*Message) Retain added in v1.1.9

func (m *Message) Retain() int32

Retain increments the reference count and returns the new value.

func (*Message) Seq

func (m *Message) Seq() uint64

Seq returns the sequence number.

func (*Message) Set

func (m *Message) Set(key interface{}, value interface{})

Set stores a key-value pair. It does nothing if key or value is nil.

func (*Message) SetAsync

func (m *Message) SetAsync(isAsync bool)

SetAsync sets or clears the async flag.

func (*Message) SetBodyLen

func (m *Message) SetBodyLen(l int)

SetBodyLen sets the body length in the header.

func (*Message) SetCmd

func (m *Message) SetCmd(cmd byte)

SetCmd sets the cmd, keeping the stream bits.

func (*Message) SetError

func (m *Message) SetError(isError bool)

SetError sets or clears the error flag.

func (*Message) SetFlagBit

func (m *Message) SetFlagBit(index int, value bool) error

SetFlagBit sets or clears bit index, 0-7, of the reserved byte, which is free for users. It returns ErrInvalidFlagBitIndex for other indexes.

func (*Message) SetMethodLen

func (m *Message) SetMethodLen(l int)

SetMethodLen sets the method length.

func (*Message) SetSeq

func (m *Message) SetSeq(seq uint64)

SetSeq sets the sequence number.

func (*Message) SetStreamEOF added in v1.2.15

func (m *Message) SetStreamEOF(eof bool)

SetStreamEOF sets or clears the stream EOF bit.

func (*Message) SetStreamLocal added in v1.2.15

func (m *Message) SetStreamLocal(local bool)

SetStreamLocal sets or clears the stream local bit.

func (*Message) Values

func (m *Message) Values() map[interface{}]interface{}

Values returns the key-value pairs attached to the Message. They are local and never sent over the wire.

type MessageCoder

type MessageCoder interface {
	// Encode transforms a Message before it is sent.
	Encode(*Client, *Message) *Message
	// Decode transforms a received Message before it is handled.
	Decode(*Client, *Message) *Message
}

MessageCoder transforms Messages on the wire, e.g. for compression or encryption. Coders are applied in order on Encode and in reverse order on Decode.

type NativeAllocator added in v1.1.9

type NativeAllocator struct{}

NativeAllocator allocates with make and lets the GC recycle buffers. It does not implement Append and AppendString, so it is not a full Allocator.

func (*NativeAllocator) Free added in v1.1.9

func (a *NativeAllocator) Free(buf []byte)

Free does nothing.

func (*NativeAllocator) Malloc added in v1.1.9

func (a *NativeAllocator) Malloc(size int) []byte

Malloc returns make([]byte, size).

func (*NativeAllocator) Realloc added in v1.1.9

func (a *NativeAllocator) Realloc(buf []byte, size int) []byte

Realloc returns buf resliced to size if its capacity is enough, otherwise a new buffer with buf's content.

type ReconnectInfo added in v1.2.18

type ReconnectInfo struct {
	// Times is the 1-based attempt number in the current reconnect round;
	// it starts over from 1 each time the connection is lost.
	Times int
	// MaxTimes is Handler.MaxReconnectTimes(); <= 0 means unlimited.
	MaxTimes int
	// Addr is the remote address of the lost connection.
	Addr string
	// Success reports whether the Dial succeeded.
	Success bool
	// Err is the Dial error, nil on success.
	Err error
}

ReconnectInfo describes a single reconnect attempt of a client-role Client. It is passed to Handler.OnReconnect after every attempt.

type Server

type Server struct {
	// Accepted counts the accepted conns (not counting those rejected by
	// MaxLoad). It is updated without atomics by the accept loop.
	Accepted int64
	// CurrLoad is the number of current conns.
	CurrLoad int64
	// MaxLoad is the max number of concurrent conns; new conns beyond it are
	// closed at once. <= 0 means unlimited.
	MaxLoad int64

	// Codec encodes and decodes message bodies.
	Codec codec.Codec
	// Handler handles the messages and events of all conns.
	Handler Handler

	// Listener is the listener being served.
	Listener net.Listener
	// contains filtered or unexported fields
}

Server is an arpc server. Each accepted conn is served by a Client in the server role, sharing the Server's Codec and Handler.

func NewServer

func NewServer() *Server

NewServer creates a Server with DefaultCodec and a clone of DefaultHandler.

func (*Server) Broadcast added in v1.2.2

func (s *Server) Broadcast(method string, v interface{}, args ...interface{})

Broadcast sends a notify to all conns. It does not block: the message is dropped for a conn whose send queue is full (see Handler.HandleOverstock). args[0], if any, must be a map[interface{}]interface{} of message values.

func (*Server) BroadcastWithFilter added in v1.2.2

func (s *Server) BroadcastWithFilter(method string, v interface{}, filter func(*Client) bool, args ...interface{})

BroadcastWithFilter is like Broadcast, but only sends to the conns for which filter returns true. A nil filter matches all.

func (*Server) ForEach added in v1.2.2

func (s *Server) ForEach(h func(*Client))

ForEach calls h for each conn. It holds the Server's lock, so h must not call methods of the Server that lock it.

func (*Server) ForEachWithFilter added in v1.2.2

func (s *Server) ForEachWithFilter(h func(*Client), filter func(*Client) bool)

ForEachWithFilter is like ForEach, but only calls h for the conns for which filter returns true. A nil filter matches all.

func (*Server) NewMessage

func (s *Server) NewMessage(cmd byte, method string, v interface{}, args ...interface{}) *Message

NewMessage creates a Message with the Server's Handler and Codec and a new sequence number. args[0], if any, must be a map[interface{}]interface{} of message values.

func (*Server) Run

func (s *Server) Run(addr string) error

Run listens on the TCP address addr and serves it, see Serve.

func (*Server) Serve

func (s *Server) Serve(ln net.Listener) error

Serve accepts conns on ln and serves them. It blocks until the Server is stopped or Accept fails with a non-temporary error, which it returns.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown closes the listener and waits for the accept loop to exit and stop all conns. It returns ErrTimeout if ctx is done first.

func (*Server) Stop

func (s *Server) Stop() error

Stop closes the listener and returns immediately, without waiting for the accept loop to exit; use Shutdown to wait. When the loop exits, all conns are stopped.

type Stream added in v1.2.15

type Stream struct {
	// contains filtered or unexported fields
}

Stream is a bidirectional message stream over a Client, identified by id and bound to a method. Each side can close its send and receive halves separately; the Stream is removed from the Client once both are closed.

func (*Stream) CloseRecv added in v1.2.15

func (s *Stream) CloseRecv()

CloseRecv closes the receive half. Messages already queued can still be read by Recv, after which it returns io.EOF.

func (*Stream) CloseRecvContext added in v1.2.15

func (s *Stream) CloseRecvContext(ctx context.Context)

CloseRecvContext is the same as CloseRecv; ctx is unused.

func (*Stream) CloseSend added in v1.2.15

func (s *Stream) CloseSend()

CloseSend closes the send half asynchronously, see CloseSendContext.

func (*Stream) CloseSendContext added in v1.2.15

func (s *Stream) CloseSendContext(ctx context.Context)

CloseSendContext closes the send half by sending an EOF message to the peer. Only the first call has effect; ctx bounds the time waiting for the send queue.

func (*Stream) Id added in v1.2.15

func (s *Stream) Id() uint64

Id returns the stream id.

func (*Stream) Recv added in v1.2.15

func (s *Stream) Recv(v interface{}) error

Recv waits for the next message and decodes it into v, see util.BytesToValue. It returns io.EOF after the receive half is closed and drained, or ErrClientStopped if the Client stops.

func (*Stream) RecvContext added in v1.2.15

func (s *Stream) RecvContext(ctx context.Context, v interface{}) error

RecvContext is like Recv, and returns ErrTimeout when ctx is done.

func (*Stream) RecvWith added in v1.2.15

func (s *Stream) RecvWith(ctx context.Context, v interface{}) error

RecvWith is an alias of RecvContext.

func (*Stream) Send added in v1.2.15

func (s *Stream) Send(v interface{}, args ...interface{}) error

Send sends v to the peer, see SendContext.

func (*Stream) SendAndClose added in v1.2.15

func (s *Stream) SendAndClose(v interface{}, args ...interface{}) error

SendAndClose sends v and closes the send half, see SendAndCloseContext.

func (*Stream) SendAndCloseContext added in v1.2.15

func (s *Stream) SendAndCloseContext(ctx context.Context, v interface{}, args ...interface{}) error

SendAndCloseContext is like SendContext, and marks the message as EOF so the send half is closed with it.

func (*Stream) SendAndCloseWith added in v1.2.15

func (s *Stream) SendAndCloseWith(ctx context.Context, v interface{}, args ...interface{}) error

SendAndCloseWith is an alias of SendAndCloseContext.

func (*Stream) SendContext added in v1.2.15

func (s *Stream) SendContext(ctx context.Context, v interface{}, args ...interface{}) error

SendContext sends v to the peer. args[0], if any, must be a map[interface{}]interface{} of message values. With AsyncWrite, ctx bounds the time waiting for the send queue. It returns ErrStreamClosedSend after the send half is closed.

func (*Stream) SendWith added in v1.2.15

func (s *Stream) SendWith(ctx context.Context, v interface{}, args ...interface{}) error

SendWith is an alias of SendContext.

type StreamHandlerFunc added in v1.2.15

type StreamHandlerFunc func(*Stream)

StreamHandlerFunc handles a Stream opened by the peer.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL