libstdc++: Qualify calls in <bits/stl_uninitialized.h> to prevent ADL
[official-gcc.git] / libgo / go / net / rpc / server.go
blobd5207a42cf1036408e378ae87e87da8cf02fe945
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.
5 /*
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
45 parameters.
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
52 transport the data.
54 Here is a simple example. A server wishes to export an object of type Arith:
56 package server
58 import "errors"
60 type Args struct {
61 A, B int
64 type Quotient struct {
65 Quo, Rem int
68 type Arith int
70 func (t *Arith) Multiply(args *Args, reply *int) error {
71 *reply = args.A * args.B
72 return nil
75 func (t *Arith) Divide(args *Args, quo *Quotient) error {
76 if args.B == 0 {
77 return errors.New("divide by zero")
79 quo.Quo = args.A / args.B
80 quo.Rem = args.A % args.B
81 return nil
84 The server calls (for HTTP service):
86 arith := new(Arith)
87 rpc.Register(arith)
88 rpc.HandleHTTP()
89 l, e := net.Listen("tcp", ":1234")
90 if e != nil {
91 log.Fatal("listen error:", e)
93 go http.Serve(l, nil)
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")
99 if err != nil {
100 log.Fatal("dialing:", err)
103 Then it can make a remote call:
105 // Synchronous call
106 args := &server.Args{7,8}
107 var reply int
108 err = client.Call("Arith.Multiply", args, &reply)
109 if err != nil {
110 log.Fatal("arith error:", err)
112 fmt.Printf("Arith: %d*%d=%d", args.A, args.B, reply)
116 // Asynchronous call
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
123 client.
125 The net/rpc package is frozen and is not accepting new features.
127 package rpc
129 import (
130 "bufio"
131 "encoding/gob"
132 "errors"
133 "go/token"
134 "io"
135 "log"
136 "net"
137 "net/http"
138 "reflect"
139 "strings"
140 "sync"
143 const (
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
156 ArgType reflect.Type
157 ReplyType reflect.Type
158 numCalls uint
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
170 // network traffic.
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
179 // network traffic.
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.
188 type Server struct {
189 serviceMap sync.Map // map[string]*service
190 reqLock sync.Mutex // protects freeReq
191 freeReq *Request
192 respLock sync.Mutex // protects freeResp
193 freeResp *Response
196 // NewServer returns a new Server.
197 func NewServer() *Server {
198 return &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 {
207 t = t.Elem()
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 {
239 s := new(service)
240 s.typ = reflect.TypeOf(rcvr)
241 s.rcvr = reflect.ValueOf(rcvr)
242 sname := reflect.Indirect(s.rcvr).Type().Name()
243 if useName {
244 sname = name
246 if sname == "" {
247 s := "rpc.Register: no service name for type " + s.typ.String()
248 log.Print(s)
249 return errors.New(s)
251 if !token.IsExported(sname) && !useName {
252 s := "rpc.Register: type " + sname + " is not exported"
253 log.Print(s)
254 return errors.New(s)
256 s.name = sname
258 // Install the methods
259 s.method = suitableMethods(s.typ, logRegisterError)
261 if len(s.method) == 0 {
262 str := ""
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)"
268 } else {
269 str = "rpc.Register: type " + sname + " has no exported methods of suitable type"
271 log.Print(str)
272 return errors.New(str)
275 if _, dup := server.serviceMap.LoadOrStore(sname, s); dup {
276 return errors.New("rpc: service already defined: " + sname)
278 return nil
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)
287 mtype := method.Type
288 mname := method.Name
289 // Method must be exported.
290 if !method.IsExported() {
291 continue
293 // Method needs three ins: receiver, *args, *reply.
294 if mtype.NumIn() != 3 {
295 if logErr {
296 log.Printf("rpc.Register: method %q has %d input parameters; needs exactly three\n", mname, mtype.NumIn())
298 continue
300 // First arg need not be a pointer.
301 argType := mtype.In(1)
302 if !isExportedOrBuiltinType(argType) {
303 if logErr {
304 log.Printf("rpc.Register: argument type of method %q is not exported: %q\n", mname, argType)
306 continue
308 // Second arg must be a pointer.
309 replyType := mtype.In(2)
310 if replyType.Kind() != reflect.Pointer {
311 if logErr {
312 log.Printf("rpc.Register: reply type of method %q is not a pointer: %q\n", mname, replyType)
314 continue
316 // Reply type must be exported.
317 if !isExportedOrBuiltinType(replyType) {
318 if logErr {
319 log.Printf("rpc.Register: reply type of method %q is not exported: %q\n", mname, replyType)
321 continue
323 // Method needs one out.
324 if mtype.NumOut() != 1 {
325 if logErr {
326 log.Printf("rpc.Register: method %q has %d output parameters; needs exactly one\n", mname, mtype.NumOut())
328 continue
330 // The return type of the method must be error.
331 if returnType := mtype.Out(0); returnType != typeOfError {
332 if logErr {
333 log.Printf("rpc.Register: return type of method %q is %q, must be error\n", mname, returnType)
335 continue
337 methods[mname] = &methodType{method: method, ArgType: argType, ReplyType: replyType}
339 return methods
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
351 if errmsg != "" {
352 resp.Error = errmsg
353 reply = invalidRequest
355 resp.Seq = req.Seq
356 sending.Lock()
357 err := codec.WriteResponse(resp, reply)
358 if debugLog && err != nil {
359 log.Println("rpc: writing response:", err)
361 sending.Unlock()
362 server.freeResponse(resp)
365 func (m *methodType) NumCalls() (n uint) {
366 m.Lock()
367 n = m.numCalls
368 m.Unlock()
369 return n
372 func (s *service) call(server *Server, sending *sync.Mutex, wg *sync.WaitGroup, mtype *methodType, req *Request, argv, replyv reflect.Value, codec ServerCodec) {
373 if wg != nil {
374 defer wg.Done()
376 mtype.Lock()
377 mtype.numCalls++
378 mtype.Unlock()
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()
384 errmsg := ""
385 if errInter != nil {
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
394 dec *gob.Decoder
395 enc *gob.Encoder
396 encBuf *bufio.Writer
397 closed bool
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)
414 c.Close()
416 return
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)
423 c.Close()
425 return
427 return c.encBuf.Flush()
430 func (c *gobServerCodec) Close() error {
431 if c.closed {
432 // Only call c.rwc.Close once; otherwise the semantics are undefined.
433 return nil
435 c.closed = true
436 return c.rwc.Close()
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{
448 rwc: conn,
449 dec: gob.NewDecoder(conn),
450 enc: gob.NewEncoder(buf),
451 encBuf: 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)
461 for {
462 service, mtype, req, argv, replyv, keepReading, err := server.readRequest(codec)
463 if err != nil {
464 if debugLog && err != io.EOF {
465 log.Println("rpc:", err)
467 if !keepReading {
468 break
470 // send a response if we actually managed to read a header.
471 if req != nil {
472 server.sendResponse(sending, req, invalidRequest, codec, err.Error())
473 server.freeRequest(req)
475 continue
477 wg.Add(1)
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.
482 wg.Wait()
483 codec.Close()
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)
491 if err != nil {
492 if !keepReading {
493 return err
495 // send a response if we actually managed to read a header.
496 if req != nil {
497 server.sendResponse(sending, req, invalidRequest, codec, err.Error())
498 server.freeRequest(req)
500 return err
502 service.call(server, sending, nil, mtype, req, argv, replyv, codec)
503 return nil
506 func (server *Server) getRequest() *Request {
507 server.reqLock.Lock()
508 req := server.freeReq
509 if req == nil {
510 req = new(Request)
511 } else {
512 server.freeReq = req.next
513 *req = Request{}
515 server.reqLock.Unlock()
516 return req
519 func (server *Server) freeRequest(req *Request) {
520 server.reqLock.Lock()
521 req.next = server.freeReq
522 server.freeReq = req
523 server.reqLock.Unlock()
526 func (server *Server) getResponse() *Response {
527 server.respLock.Lock()
528 resp := server.freeResp
529 if resp == nil {
530 resp = new(Response)
531 } else {
532 server.freeResp = resp.next
533 *resp = Response{}
535 server.respLock.Unlock()
536 return resp
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)
548 if err != nil {
549 if !keepReading {
550 return
552 // discard body
553 codec.ReadRequestBody(nil)
554 return
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())
561 } else {
562 argv = reflect.New(mtype.ArgType)
563 argIsValue = true
565 // argv guaranteed to be a pointer now.
566 if err = codec.ReadRequestBody(argv.Interface()); err != nil {
567 return
569 if argIsValue {
570 argv = argv.Elem()
573 replyv = reflect.New(mtype.ReplyType.Elem())
575 switch mtype.ReplyType.Elem().Kind() {
576 case reflect.Map:
577 replyv.Elem().Set(reflect.MakeMap(mtype.ReplyType.Elem()))
578 case reflect.Slice:
579 replyv.Elem().Set(reflect.MakeSlice(mtype.ReplyType.Elem(), 0, 0))
581 return
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)
588 if err != nil {
589 req = nil
590 if err == io.EOF || err == io.ErrUnexpectedEOF {
591 return
593 err = errors.New("rpc: server cannot decode request: " + err.Error())
594 return
597 // We read the header successfully. If we see an error now,
598 // we can still recover and move on to the next request.
599 keepReading = true
601 dot := strings.LastIndex(req.ServiceMethod, ".")
602 if dot < 0 {
603 err = errors.New("rpc: service/method request ill-formed: " + req.ServiceMethod)
604 return
606 serviceName := req.ServiceMethod[:dot]
607 methodName := req.ServiceMethod[dot+1:]
609 // Look up the request.
610 svci, ok := server.serviceMap.Load(serviceName)
611 if !ok {
612 err = errors.New("rpc: can't find service " + req.ServiceMethod)
613 return
615 svc = svci.(*service)
616 mtype = svc.method[methodName]
617 if mtype == nil {
618 err = errors.New("rpc: can't find method " + req.ServiceMethod)
620 return
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
626 // go statement.
627 func (server *Server) Accept(lis net.Listener) {
628 for {
629 conn, err := lis.Accept()
630 if err != nil {
631 log.Print("rpc.Serve: accept:", err.Error())
632 return
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.
661 Close() error
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")
700 return
702 conn, _, err := w.(http.Hijacker).Hijack()
703 if err != nil {
704 log.Print("rpc hijacking ", req.RemoteAddr, ": ", err.Error())
705 return
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.
722 func HandleHTTP() {
723 DefaultServer.HandleHTTP(DefaultRPCPath, DefaultDebugPath)