1 // Copyright 2009 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
6 Package rpc provides access to the exported methods of an object across a
7 network or other I/O connection. A server registers an object, making it visible
8 as a service with the name of the type of the object. After registration, exported
9 methods of the object will be accessible remotely. A server may register multiple
10 objects (services) of different types but it is an error to register multiple
11 objects of the same type.
13 Only methods that satisfy these criteria will be made available for remote access;
14 other methods will be ignored:
16 - the method's type is exported.
17 - the method is exported.
18 - the method has two arguments, both exported (or builtin) types.
19 - the method's second argument is a pointer.
20 - the method has return type error.
22 In effect, the method must look schematically like
24 func (t *T) MethodName(argType T1, replyType *T2) error
26 where T1 and T2 can be marshaled by encoding/gob.
27 These requirements apply even if a different codec is used.
28 (In the future, these requirements may soften for custom codecs.)
30 The method's first argument represents the arguments provided by the caller; the
31 second argument represents the result parameters to be returned to the caller.
32 The method's return value, if non-nil, is passed back as a string that the client
33 sees as if created by errors.New. If an error is returned, the reply parameter
34 will not be sent back to the client.
36 The server may handle requests on a single connection by calling ServeConn. More
37 typically it will create a network listener and call Accept or, for an HTTP
38 listener, HandleHTTP and http.Serve.
40 A client wishing to use the service establishes a connection and then invokes
41 NewClient on the connection. The convenience function Dial (DialHTTP) performs
42 both steps for a raw network connection (an HTTP connection). The resulting
43 Client object has two methods, Call and Go, that specify the service and method to
44 call, a pointer containing the arguments, and a pointer to receive the result
47 The Call method waits for the remote call to complete while the Go method
48 launches the call asynchronously and signals completion using the Call
49 structure's Done channel.
51 Unless an explicit codec is set up, package encoding/gob is used to
54 Here is a simple example. A server wishes to export an object of type Arith:
64 type Quotient struct {
70 func (t *Arith) Multiply(args *Args, reply *int) error {
71 *reply = args.A * args.B
75 func (t *Arith) Divide(args *Args, quo *Quotient) error {
77 return errors.New("divide by zero")
79 quo.Quo = args.A / args.B
80 quo.Rem = args.A % args.B
84 The server calls (for HTTP service):
89 l, e := net.Listen("tcp", ":1234")
91 log.Fatal("listen error:", e)
95 At this point, clients can see a service "Arith" with methods "Arith.Multiply" and
96 "Arith.Divide". To invoke one, a client first dials the server:
98 client, err := rpc.DialHTTP("tcp", serverAddress + ":1234")
100 log.Fatal("dialing:", err)
103 Then it can make a remote call:
106 args := &server.Args{7,8}
108 err = client.Call("Arith.Multiply", args, &reply)
110 log.Fatal("arith error:", err)
112 fmt.Printf("Arith: %d*%d=%d", args.A, args.B, reply)
117 quotient := new(Quotient)
118 divCall := client.Go("Arith.Divide", args, quotient, nil)
119 replyCall := <-divCall.Done // will be equal to divCall
120 // check errors, print, etc.
122 A server implementation will often provide a simple, type-safe wrapper for the
125 The net/rpc package is frozen and is not accepting new features.
144 // Defaults used by HandleHTTP
145 DefaultRPCPath
= "/_goRPC_"
146 DefaultDebugPath
= "/debug/rpc"
149 // Precompute the reflect type for error. Can't use error directly
150 // because Typeof takes an empty interface value. This is annoying.
151 var typeOfError
= reflect
.TypeOf((*error
)(nil)).Elem()
153 type methodType
struct {
154 sync
.Mutex
// protects counters
155 method reflect
.Method
157 ReplyType reflect
.Type
161 type service
struct {
162 name
string // name of service
163 rcvr reflect
.Value
// receiver of methods for the service
164 typ reflect
.Type
// type of the receiver
165 method
map[string]*methodType
// registered methods
168 // Request is a header written before every RPC call. It is used internally
169 // but documented here as an aid to debugging, such as when analyzing
171 type Request
struct {
172 ServiceMethod
string // format: "Service.Method"
173 Seq
uint64 // sequence number chosen by client
174 next
*Request
// for free list in Server
177 // Response is a header written before every RPC return. It is used internally
178 // but documented here as an aid to debugging, such as when analyzing
180 type Response
struct {
181 ServiceMethod
string // echoes that of the Request
182 Seq
uint64 // echoes that of the request
183 Error
string // error, if any.
184 next
*Response
// for free list in Server
187 // Server represents an RPC Server.
189 serviceMap sync
.Map
// map[string]*service
190 reqLock sync
.Mutex
// protects freeReq
192 respLock sync
.Mutex
// protects freeResp
196 // NewServer returns a new Server.
197 func NewServer() *Server
{
201 // DefaultServer is the default instance of *Server.
202 var DefaultServer
= NewServer()
204 // Is this type exported or a builtin?
205 func isExportedOrBuiltinType(t reflect
.Type
) bool {
206 for t
.Kind() == reflect
.Pointer
{
209 // PkgPath will be non-empty even for an exported type,
210 // so we need to check the type name as well.
211 return token
.IsExported(t
.Name()) || t
.PkgPath() == ""
214 // Register publishes in the server the set of methods of the
215 // receiver value that satisfy the following conditions:
216 // - exported method of exported type
217 // - two arguments, both of exported type
218 // - the second argument is a pointer
219 // - one return value, of type error
220 // It returns an error if the receiver is not an exported type or has
221 // no suitable methods. It also logs the error using package log.
222 // The client accesses each method using a string of the form "Type.Method",
223 // where Type is the receiver's concrete type.
224 func (server
*Server
) Register(rcvr any
) error
{
225 return server
.register(rcvr
, "", false)
228 // RegisterName is like Register but uses the provided name for the type
229 // instead of the receiver's concrete type.
230 func (server
*Server
) RegisterName(name
string, rcvr any
) error
{
231 return server
.register(rcvr
, name
, true)
234 // logRegisterError specifies whether to log problems during method registration.
235 // To debug registration, recompile the package with this set to true.
236 const logRegisterError
= false
238 func (server
*Server
) register(rcvr any
, name
string, useName
bool) error
{
240 s
.typ
= reflect
.TypeOf(rcvr
)
241 s
.rcvr
= reflect
.ValueOf(rcvr
)
242 sname
:= reflect
.Indirect(s
.rcvr
).Type().Name()
247 s
:= "rpc.Register: no service name for type " + s
.typ
.String()
251 if !token
.IsExported(sname
) && !useName
{
252 s
:= "rpc.Register: type " + sname
+ " is not exported"
258 // Install the methods
259 s
.method
= suitableMethods(s
.typ
, logRegisterError
)
261 if len(s
.method
) == 0 {
264 // To help the user, see if a pointer receiver would work.
265 method
:= suitableMethods(reflect
.PointerTo(s
.typ
), false)
266 if len(method
) != 0 {
267 str
= "rpc.Register: type " + sname
+ " has no exported methods of suitable type (hint: pass a pointer to value of that type)"
269 str
= "rpc.Register: type " + sname
+ " has no exported methods of suitable type"
272 return errors
.New(str
)
275 if _
, dup
:= server
.serviceMap
.LoadOrStore(sname
, s
); dup
{
276 return errors
.New("rpc: service already defined: " + sname
)
281 // suitableMethods returns suitable Rpc methods of typ. It will log
282 // errors if logErr is true.
283 func suitableMethods(typ reflect
.Type
, logErr
bool) map[string]*methodType
{
284 methods
:= make(map[string]*methodType
)
285 for m
:= 0; m
< typ
.NumMethod(); m
++ {
286 method
:= typ
.Method(m
)
289 // Method must be exported.
290 if !method
.IsExported() {
293 // Method needs three ins: receiver, *args, *reply.
294 if mtype
.NumIn() != 3 {
296 log
.Printf("rpc.Register: method %q has %d input parameters; needs exactly three\n", mname
, mtype
.NumIn())
300 // First arg need not be a pointer.
301 argType
:= mtype
.In(1)
302 if !isExportedOrBuiltinType(argType
) {
304 log
.Printf("rpc.Register: argument type of method %q is not exported: %q\n", mname
, argType
)
308 // Second arg must be a pointer.
309 replyType
:= mtype
.In(2)
310 if replyType
.Kind() != reflect
.Pointer
{
312 log
.Printf("rpc.Register: reply type of method %q is not a pointer: %q\n", mname
, replyType
)
316 // Reply type must be exported.
317 if !isExportedOrBuiltinType(replyType
) {
319 log
.Printf("rpc.Register: reply type of method %q is not exported: %q\n", mname
, replyType
)
323 // Method needs one out.
324 if mtype
.NumOut() != 1 {
326 log
.Printf("rpc.Register: method %q has %d output parameters; needs exactly one\n", mname
, mtype
.NumOut())
330 // The return type of the method must be error.
331 if returnType
:= mtype
.Out(0); returnType
!= typeOfError
{
333 log
.Printf("rpc.Register: return type of method %q is %q, must be error\n", mname
, returnType
)
337 methods
[mname
] = &methodType
{method
: method
, ArgType
: argType
, ReplyType
: replyType
}
342 // A value sent as a placeholder for the server's response value when the server
343 // receives an invalid request. It is never decoded by the client since the Response
344 // contains an error when it is used.
345 var invalidRequest
= struct{}{}
347 func (server
*Server
) sendResponse(sending
*sync
.Mutex
, req
*Request
, reply any
, codec ServerCodec
, errmsg
string) {
348 resp
:= server
.getResponse()
349 // Encode the response header
350 resp
.ServiceMethod
= req
.ServiceMethod
353 reply
= invalidRequest
357 err
:= codec
.WriteResponse(resp
, reply
)
358 if debugLog
&& err
!= nil {
359 log
.Println("rpc: writing response:", err
)
362 server
.freeResponse(resp
)
365 func (m
*methodType
) NumCalls() (n
uint) {
372 func (s
*service
) call(server
*Server
, sending
*sync
.Mutex
, wg
*sync
.WaitGroup
, mtype
*methodType
, req
*Request
, argv
, replyv reflect
.Value
, codec ServerCodec
) {
379 function
:= mtype
.method
.Func
380 // Invoke the method, providing a new value for the reply.
381 returnValues
:= function
.Call([]reflect
.Value
{s
.rcvr
, argv
, replyv
})
382 // The return value for the method is an error.
383 errInter
:= returnValues
[0].Interface()
386 errmsg
= errInter
.(error
).Error()
388 server
.sendResponse(sending
, req
, replyv
.Interface(), codec
, errmsg
)
389 server
.freeRequest(req
)
392 type gobServerCodec
struct {
393 rwc io
.ReadWriteCloser
400 func (c
*gobServerCodec
) ReadRequestHeader(r
*Request
) error
{
401 return c
.dec
.Decode(r
)
404 func (c
*gobServerCodec
) ReadRequestBody(body any
) error
{
405 return c
.dec
.Decode(body
)
408 func (c
*gobServerCodec
) WriteResponse(r
*Response
, body any
) (err error
) {
409 if err
= c
.enc
.Encode(r
); err
!= nil {
410 if c
.encBuf
.Flush() == nil {
411 // Gob couldn't encode the header. Should not happen, so if it does,
412 // shut down the connection to signal that the connection is broken.
413 log
.Println("rpc: gob error encoding response:", err
)
418 if err
= c
.enc
.Encode(body
); err
!= nil {
419 if c
.encBuf
.Flush() == nil {
420 // Was a gob problem encoding the body but the header has been written.
421 // Shut down the connection to signal that the connection is broken.
422 log
.Println("rpc: gob error encoding body:", err
)
427 return c
.encBuf
.Flush()
430 func (c
*gobServerCodec
) Close() error
{
432 // Only call c.rwc.Close once; otherwise the semantics are undefined.
439 // ServeConn runs the server on a single connection.
440 // ServeConn blocks, serving the connection until the client hangs up.
441 // The caller typically invokes ServeConn in a go statement.
442 // ServeConn uses the gob wire format (see package gob) on the
443 // connection. To use an alternate codec, use ServeCodec.
444 // See NewClient's comment for information about concurrent access.
445 func (server
*Server
) ServeConn(conn io
.ReadWriteCloser
) {
446 buf
:= bufio
.NewWriter(conn
)
447 srv
:= &gobServerCodec
{
449 dec
: gob
.NewDecoder(conn
),
450 enc
: gob
.NewEncoder(buf
),
453 server
.ServeCodec(srv
)
456 // ServeCodec is like ServeConn but uses the specified codec to
457 // decode requests and encode responses.
458 func (server
*Server
) ServeCodec(codec ServerCodec
) {
459 sending
:= new(sync
.Mutex
)
460 wg
:= new(sync
.WaitGroup
)
462 service
, mtype
, req
, argv
, replyv
, keepReading
, err
:= server
.readRequest(codec
)
464 if debugLog
&& err
!= io
.EOF
{
465 log
.Println("rpc:", err
)
470 // send a response if we actually managed to read a header.
472 server
.sendResponse(sending
, req
, invalidRequest
, codec
, err
.Error())
473 server
.freeRequest(req
)
478 go service
.call(server
, sending
, wg
, mtype
, req
, argv
, replyv
, codec
)
480 // We've seen that there are no more requests.
481 // Wait for responses to be sent before closing codec.
486 // ServeRequest is like ServeCodec but synchronously serves a single request.
487 // It does not close the codec upon completion.
488 func (server
*Server
) ServeRequest(codec ServerCodec
) error
{
489 sending
:= new(sync
.Mutex
)
490 service
, mtype
, req
, argv
, replyv
, keepReading
, err
:= server
.readRequest(codec
)
495 // send a response if we actually managed to read a header.
497 server
.sendResponse(sending
, req
, invalidRequest
, codec
, err
.Error())
498 server
.freeRequest(req
)
502 service
.call(server
, sending
, nil, mtype
, req
, argv
, replyv
, codec
)
506 func (server
*Server
) getRequest() *Request
{
507 server
.reqLock
.Lock()
508 req
:= server
.freeReq
512 server
.freeReq
= req
.next
515 server
.reqLock
.Unlock()
519 func (server
*Server
) freeRequest(req
*Request
) {
520 server
.reqLock
.Lock()
521 req
.next
= server
.freeReq
523 server
.reqLock
.Unlock()
526 func (server
*Server
) getResponse() *Response
{
527 server
.respLock
.Lock()
528 resp
:= server
.freeResp
532 server
.freeResp
= resp
.next
535 server
.respLock
.Unlock()
539 func (server
*Server
) freeResponse(resp
*Response
) {
540 server
.respLock
.Lock()
541 resp
.next
= server
.freeResp
542 server
.freeResp
= resp
543 server
.respLock
.Unlock()
546 func (server
*Server
) readRequest(codec ServerCodec
) (service
*service
, mtype
*methodType
, req
*Request
, argv
, replyv reflect
.Value
, keepReading
bool, err error
) {
547 service
, mtype
, req
, keepReading
, err
= server
.readRequestHeader(codec
)
553 codec
.ReadRequestBody(nil)
557 // Decode the argument value.
558 argIsValue
:= false // if true, need to indirect before calling.
559 if mtype
.ArgType
.Kind() == reflect
.Pointer
{
560 argv
= reflect
.New(mtype
.ArgType
.Elem())
562 argv
= reflect
.New(mtype
.ArgType
)
565 // argv guaranteed to be a pointer now.
566 if err
= codec
.ReadRequestBody(argv
.Interface()); err
!= nil {
573 replyv
= reflect
.New(mtype
.ReplyType
.Elem())
575 switch mtype
.ReplyType
.Elem().Kind() {
577 replyv
.Elem().Set(reflect
.MakeMap(mtype
.ReplyType
.Elem()))
579 replyv
.Elem().Set(reflect
.MakeSlice(mtype
.ReplyType
.Elem(), 0, 0))
584 func (server
*Server
) readRequestHeader(codec ServerCodec
) (svc
*service
, mtype
*methodType
, req
*Request
, keepReading
bool, err error
) {
585 // Grab the request header.
586 req
= server
.getRequest()
587 err
= codec
.ReadRequestHeader(req
)
590 if err
== io
.EOF || err
== io
.ErrUnexpectedEOF
{
593 err
= errors
.New("rpc: server cannot decode request: " + err
.Error())
597 // We read the header successfully. If we see an error now,
598 // we can still recover and move on to the next request.
601 dot
:= strings
.LastIndex(req
.ServiceMethod
, ".")
603 err
= errors
.New("rpc: service/method request ill-formed: " + req
.ServiceMethod
)
606 serviceName
:= req
.ServiceMethod
[:dot
]
607 methodName
:= req
.ServiceMethod
[dot
+1:]
609 // Look up the request.
610 svci
, ok
:= server
.serviceMap
.Load(serviceName
)
612 err
= errors
.New("rpc: can't find service " + req
.ServiceMethod
)
615 svc
= svci
.(*service
)
616 mtype
= svc
.method
[methodName
]
618 err
= errors
.New("rpc: can't find method " + req
.ServiceMethod
)
623 // Accept accepts connections on the listener and serves requests
624 // for each incoming connection. Accept blocks until the listener
625 // returns a non-nil error. The caller typically invokes Accept in a
627 func (server
*Server
) Accept(lis net
.Listener
) {
629 conn
, err
:= lis
.Accept()
631 log
.Print("rpc.Serve: accept:", err
.Error())
634 go server
.ServeConn(conn
)
638 // Register publishes the receiver's methods in the DefaultServer.
639 func Register(rcvr any
) error
{ return DefaultServer
.Register(rcvr
) }
641 // RegisterName is like Register but uses the provided name for the type
642 // instead of the receiver's concrete type.
643 func RegisterName(name
string, rcvr any
) error
{
644 return DefaultServer
.RegisterName(name
, rcvr
)
647 // A ServerCodec implements reading of RPC requests and writing of
648 // RPC responses for the server side of an RPC session.
649 // The server calls ReadRequestHeader and ReadRequestBody in pairs
650 // to read requests from the connection, and it calls WriteResponse to
651 // write a response back. The server calls Close when finished with the
652 // connection. ReadRequestBody may be called with a nil
653 // argument to force the body of the request to be read and discarded.
654 // See NewClient's comment for information about concurrent access.
655 type ServerCodec
interface {
656 ReadRequestHeader(*Request
) error
657 ReadRequestBody(any
) error
658 WriteResponse(*Response
, any
) error
660 // Close can be called multiple times and must be idempotent.
664 // ServeConn runs the DefaultServer on a single connection.
665 // ServeConn blocks, serving the connection until the client hangs up.
666 // The caller typically invokes ServeConn in a go statement.
667 // ServeConn uses the gob wire format (see package gob) on the
668 // connection. To use an alternate codec, use ServeCodec.
669 // See NewClient's comment for information about concurrent access.
670 func ServeConn(conn io
.ReadWriteCloser
) {
671 DefaultServer
.ServeConn(conn
)
674 // ServeCodec is like ServeConn but uses the specified codec to
675 // decode requests and encode responses.
676 func ServeCodec(codec ServerCodec
) {
677 DefaultServer
.ServeCodec(codec
)
680 // ServeRequest is like ServeCodec but synchronously serves a single request.
681 // It does not close the codec upon completion.
682 func ServeRequest(codec ServerCodec
) error
{
683 return DefaultServer
.ServeRequest(codec
)
686 // Accept accepts connections on the listener and serves requests
687 // to DefaultServer for each incoming connection.
688 // Accept blocks; the caller typically invokes it in a go statement.
689 func Accept(lis net
.Listener
) { DefaultServer
.Accept(lis
) }
691 // Can connect to RPC service using HTTP CONNECT to rpcPath.
692 var connected
= "200 Connected to Go RPC"
694 // ServeHTTP implements an http.Handler that answers RPC requests.
695 func (server
*Server
) ServeHTTP(w http
.ResponseWriter
, req
*http
.Request
) {
696 if req
.Method
!= "CONNECT" {
697 w
.Header().Set("Content-Type", "text/plain; charset=utf-8")
698 w
.WriteHeader(http
.StatusMethodNotAllowed
)
699 io
.WriteString(w
, "405 must CONNECT\n")
702 conn
, _
, err
:= w
.(http
.Hijacker
).Hijack()
704 log
.Print("rpc hijacking ", req
.RemoteAddr
, ": ", err
.Error())
707 io
.WriteString(conn
, "HTTP/1.0 "+connected
+"\n\n")
708 server
.ServeConn(conn
)
711 // HandleHTTP registers an HTTP handler for RPC messages on rpcPath,
712 // and a debugging handler on debugPath.
713 // It is still necessary to invoke http.Serve(), typically in a go statement.
714 func (server
*Server
) HandleHTTP(rpcPath
, debugPath
string) {
715 http
.Handle(rpcPath
, server
)
716 http
.Handle(debugPath
, debugHTTP
{server
})
719 // HandleHTTP registers an HTTP handler for RPC messages to DefaultServer
720 // on DefaultRPCPath and a debugging handler on DefaultDebugPath.
721 // It is still necessary to invoke http.Serve(), typically in a go statement.
723 DefaultServer
.HandleHTTP(DefaultRPCPath
, DefaultDebugPath
)