trpc.group/trpc-go/trpc-go@v1.0.3/docs/user_guide/graceful_restart.md (about)

     1  English | [中文](graceful_restart.zh_CN.md)
     2  
     3  # Introduction
     4  
     5  The tRPC-Go framework supports graceful restart (hot restart). During the restart process, established connections are not interrupted to ensure that accepted requests are handled correctly (including consumer services), while allowing the new process to establish a new connection and handle new requests.
     6  
     7  # Implementation
     8  
     9  tRPC-Go's implementation of graceful restart can be described as follows:
    10  - The service listens on the SIGUSR2 signal as the graceful restart signal (customizable).
    11  - The service process keeps track of each server transport's listenfd.
    12  - When the process accepts the SIGUSR2 signal, it starts the graceful restart logic.
    13  - The process uses ForkExec (instead of Fork) to create a new process with a new binary and uses ProcAttr to pass listenfd to the child process. The child process checks the environment variable to know if it is a graceful restart and obtains the initial value and amount for listenfd.
    14  - The child process starts normally but checks for graceful restart when initializing server transport. If it is gracefully restarting, it inherits from the parent's listenfd and reconstructs the listener; otherwise, it starts normally.
    15  - After the child process starts, it immediately starts serving. The parent process exits at a suitable time (e.g., shutdown tcpconn read, consumer stopped, service requested all handled) after the child process started successfully.
    16  
    17  # Implementation Details
    18  
    19  Refer to `server/serve_unix.go` and search for `DefaultServerGracefulSIG` for implementation details.
    20  
    21  # Usage Example
    22  
    23  ## Trigger graceful restart
    24  
    25  After the server is started, use `ps -ef | grep server_name` to obtain the pid, then use `kill` to send `SIGUSR2` to the process.
    26  
    27  ```bash
    28  $ kill -SIGUSR2 pid
    29  ```
    30  
    31  The command above will trigger graceful restart.
    32  
    33  ## Use custom signal
    34  
    35  By default, the signal for graceful restart is SIGUSR2. You can modify the signal before `s.Serve`, for example:
    36  
    37  ```go
    38  import "trpc.group/trpc-go/trpc-go/server"
    39  
    40  func main() {
    41      server.DefaultServerGracefulSIG = syscall.SIGUSR1
    42  }
    43  ```
    44  
    45  ## Register shutdown hooks
    46  
    47  You can register hooks to run on process exit for resource cleanup, for example:
    48  
    49  ```go
    50  import (
    51    trpc "trpc.group/trpc-go/trpc-go"
    52      "trpc.group/trpc-go/trpc-go/server"
    53  )
    54  
    55  func main() {
    56      s := trpc.NewServer()
    57      s.RegisterOnShutdown(func() { /* Your logic. */ })
    58      // ...
    59  }
    60  ```
    61  
    62  If your plugin needs to do cleanup on process exit, you can implement the `plugin.Closer` interface. The `Close` method will be called by the framework on exit (reverse order of plugins setup):
    63  
    64  ```go
    65  type closablePlugin struct{}
    66  
    67  // Type and Setup are a plugin's required methods
    68  func (p *closablePlugin) Type() string {...}
    69  func (p *closablePlugin) Setup(name string, dec Decoder) error {...}
    70  
    71  // Plugins can optionally implement a Close method, for resource cleanup on process exit
    72  func (p *closablePlugin) Close() error {...}
    73  ```