# README
Shmipc
English | 中文
Introduction
Shmipc is a high performance inter-process communication library developed by ByteDance. It is built on Linux's shared memory technology and uses unix or tcp connection to do process synchronization and finally implements zero copy communication across inter-processes. In IO-intensive or large-package scenarios, it has better performance.
Features
Zero copy
In an industrial production environment, the unix domain socket and tcp loopback are often used in inter-process communication.The read operation or the write operation need copy data between user space buffer and kernel space buffer.But shmipc directly store data to the share memory, so no copy compared to the former.
batch IO
An IO queue was mapped to share memory, which describe the metadata of communication data. so that a process could put many request to the IO queue, and other process could handle a batch IO per synchronization. It could effectively reduce the system calls which was brought by process synchronization.
Performance Testing
The source code bench_test.go, doing a performance comparison between shmipc and unix domain in ping-pong scenario with different package size. The result is as follows: having a performance improvement whatever small package or large package.
go test -bench=BenchmarkParallelPingPong -run BenchmarkParallelPingPong
goos: linux
goarch: amd64
pkg: github.com/cloudwego/shmipc-go
cpu: Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz
BenchmarkParallelPingPongByShmipc64B-40 733821 1970 ns/op 64.97 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByShmipc512B-40 536190 1990 ns/op 514.45 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByShmipc1KB-40 540517 2045 ns/op 1001.62 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByShmipc4KB-40 509047 2063 ns/op 3970.91 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByShmipc16KB-40 590398 1996 ns/op 16419.46 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByShmipc32KB-40 607756 1937 ns/op 33829.82 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByShmipc64KB-40 609824 1995 ns/op 65689.31 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByShmipc256KB-40 622755 1793 ns/op 292363.56 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByShmipc512KB-40 695401 1993 ns/op 526171.77 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByShmipc1MB-40 538208 1873 ns/op 1119401.64 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByShmipc4MB-40 606144 1891 ns/op 4436936.93 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByUds64B-40 446019 2657 ns/op 48.18 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByUds512B-40 450124 2665 ns/op 384.30 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByUds1KB-40 446389 2680 ns/op 764.29 MB/s 0 B/op 0 allocs/op
BenchmarkParallelPingPongByUds4KB-40 383552 3093 ns/op 2648.83 MB/s 1 B/op 0 allocs/op
BenchmarkParallelPingPongByUds16KB-40 307816 3884 ns/op 8436.27 MB/s 8 B/op 0 allocs/op
BenchmarkParallelPingPongByUds64KB-40 103027 10259 ns/op 12776.17 MB/s 102 B/op 0 allocs/op
BenchmarkParallelPingPongByUds256KB-40 25286 46352 ns/op 11311.01 MB/s 1661 B/op 0 allocs/op
BenchmarkParallelPingPongByUds512KB-40 9788 122873 ns/op 8533.84 MB/s 8576 B/op 0 allocs/op
BenchmarkParallelPingPongByUds1MB-40 4177 283729 ns/op 7391.38 MB/s 40178 B/op 0 allocs/op
BenchmarkParallelPingPongByUds4MB-40 919 1253338 ns/op 6693.01 MB/s 730296 B/op 1 allocs/op
PASS
ok github.com/cloudwego/shmipc 42.138s
- BenchmarkParallelPingPongByUds, the ping-pong communication base on Unix domain socket.
- BenchmarkParallelPingPongByShmipc, the ping-pong communication base on shmipc.
- the suffix of the testing case name is the package size of communication, which from 64 Byte to 4 MB.
Quick start
HelloWorld
Integrate with application
- serialization and deserialization
- client which using synchronous interface
- server which using synchronous interface
- client which using asynchronous interface
- server which using asynchronous interface
HotRestart
# Packages
No description provided by the author
# Functions
DebugBufferListDetail print all BufferList's status in share memory located in the `path`if MemMapType is MemMapTypeMemFd, you could using the command that`lsof -p $PID` to found the share memory which was mmap by memfd,and the command `cat /proc/$PID/$MEMFD > $path` dump the share memory to file system.
DebugQueueDetail print IO-Queue's status which was mmap in the `path`.
DefaultConfig is used to return a default configuration.
DefaultSessionManagerConfig return the default SessionManager's configuration.
GlobalSessionManager return a global SessionManager.
InitGlobalSessionManager initializes a global SessionManager and could use in every where in process.
Listen create listener with default backlog size(4096) shmIPCAddress is uds address used as underlying connection, the returned value is net.Listener Remember close the listener if it is created successfully, or goroutine may leak Should I use Listen? If you want the best performance, you should use low level API(not this one) to marshal and unmarshal manually, which can achieve better batch results.
ListenWithBacklog create listener with given backlog size shmIPCAddress is uds address used as underlying connection, the returned value is net.Listener Remember close the listener if it is created successfully, or goroutine may leak Should I use ListenWithBacklog? If you want the best performance, you should use low level API(not this one) to marshal and unmarshal manually, which can achieve better batch results.
linux 3.17+ provided.
NewDefaultListenerConfig return the default Listener's config.
NewListener will try listen the ListenPath of the configuration, and return the Listener if no error happened.
NewSessionManager return a SessionManager with giving configuration.
Server return a shmipc server with the giving connection and configuration.
SetLogLevel used to change the internal logger's level and the default level is Warning.The process env `SHMIPC_LOG_LEVEL` also could set log level.
VerifyConfig is used to verify the sanity of configuration.
# Constants
MemMapTypeDevShmFile maps share memory to /dev/shm (tmpfs).
MemMapTypeMemFd maps share memory to memfd (Linux OS v3.17+).
# Variables
ErrArchNonSupported means that shmipc only support amd64 and arm64.
ErrConnectionWriteTimeout means that the write timeout was happened in tcp/unix connection.
ErrEndOfStream means that the stream is end, user shouldn't to read from the stream.
ErrFileNameTooLong mean that eht Config.ShareMemoryPathPrefixFile's length reached the limitation of the OS.
ErrHotRestartInProgress was returned by Listener.HotRestart when the Session had under the hot restart state.
ErrInHandshakeStage was happened in the case that the uninitialized session doing hot restart.
ErrInvalidMsgType means that we received a message with an invalid message type.
ErrInvalidVersion means that we received a message with an invalid version.
ErrNoMoreBuffer means that the share memory is busy, and not more buffer to allocate.
ErrNotEnoughData means that the real read size < expect read size.
ErrOSNonSupported means that shmipc couldn't work in current OS.
ErrQueueFull mean that the server is so busy that the io queue is full.
ErrSessionShutdown means that the session is shutdown.
ErrSessionUnhealthy occurred at Session.OpenStream(), which mean that the session is overload.user should retry after 60 seconds(now).
ErrShareMemoryHadNotLeftSpace means that reached the limitation of the file system when using MemMapTypeDevShm.
ErrStreamCallbackHadExisted was returned if the Stream'Callbacks had existed.
ErrStreamClosed was returned when using a closed stream.
ErrStreamsExhausted means that the stream id was used out and maybe have some streams leaked.
ErrTimeout is used when we reach an IO deadline.
# Structs
Config is used to tune the shmipc session.
Listener listen socket and accept connection as shmipc server connection.
ListenerConfig is the configuration of Listener.
PerformanceMetrics is the metrics about performance.
Session is used to wrap a reliable ordered connection and to multiplex it into multiple streams.
SessionManager will start multi Session with the peer process.
SessionManagerConfig is the configuration of SessionManager.
ShareMemoryMetrics is the metrics about share memory's status.
A SizePercentPair describe a buffer list's specification.
StabilityMetrics is the metrics about stability.
Stream is used to represent a logical stream within a session.
# Interfaces
BufferReader used to read data from stream.
BufferWriter used to write data to stream.
ListenCallback is server's asynchronous API.
Monitor could emit some metrics with periodically.
StreamCallbacks provide asynchronous programming mode for improving performance in some scenarios.
# Type aliases
MemMapType is the mapping type of shared memory.