简体中文README
PhxPaxos is a state-synchronization lib based on Paxos protocol, it is totally designed by Wechat independently. It can help your services in synchronizing the state from a single node to the other nodes to form a multi-copy cluster and handling fail-over automatically by calling functions in our lib.
This lib has been used in Wechat production environment, we have also tested it in a large number of harsh environments to guarantee a stable consistency.
Authors: Haochuan Cui, Ming Chen, Junchao Chen and Duokai Huang
Contact us: phxteam@tencent.com
Principle details(Chinese)
PhxPaxos 
Features
- Purely based on Paxos Made Simple by Lamport.
- Transfering message in a async mechanism architecture.
- Using
fsync to guarantee the correctness in every IO write operations.
- Latency of a successful
Propose is one RTT and one IO write.
- Using P2P stream protocol to learn paxos log.
- Cleaning
Checkpoint and PaxosLog automatically.
- Pulling
Checkpoint across nodes automatically.
- Supporting more than one state-machines in a single PhxPaxos Instance.
- Supporting recover checkpoint by snapshot+paxoslog automatically.
- Implementing Master election as a state-machine embedded in PhxPaxos
- Implementing reconfiguration as a state-machine embedded in PhxPaxos
- Using signature algorithm embedded in PhxPaxos to recognise invalid hosts.
- Using checksum to verifying the data consistency of increment data in realtime.
- Implementing Network, Stroage, Monitor, Logging module as a plugin, they can be implemented customly
- Supporting overload protection in a self-adaption way.
Limitations
- Only a single process (possibly multi-threaded) can run a PhxPaxos instance at a time.
- There is no client-server support builtin to the library. An application that needs such support will have to wrap their own server around the library.
- PhxPaxos was only tested on Linux 64bit platform so far.
Performance
Setup
CPU: 24 x Intel(R) Xeon(R) CPU E5-2420 0 @ 1.90GHz
Memory: 2 GB
Disk: ssd raid5
Network: Gigabit Ethernet
Cluster Nodes: 3
Ping: 0.05ms
Parallel client: 100 Threads
Performance Test Result(QPS)
Request latency small than 10ms.
Data set with small size(100B)
1 Group: 1171
20 Groups: 11931
50 Groups: 13424
100 Groups: 13962
Data set with larse size(100KB)
1 Group: 280
20 Groups: 984
50 Groups: 1054
100 Groups: 1067
BatchPropose(2KB)
100 Groups: 150000
Code Directory Introduction
include: This directory includes all head files while using PhxPaxos. You may make some mistakes if you don't understand all the functions in this directory completely.
NOTE: The public interface is in include/*.h. Callers should not include or rely on the details of any other header files in this package. Those internal APIs may be changed without warning.
src: This directory includes all implementation of Phapaxos, You can figure out the working principle of PhxPaoxs by reading this directorys. No neccessary to read it if you are only using PhxPaxos.
third_party: This directory is designed to place all third party libs for compiling and running PhxPaxos. You can get a detail in the following compilation section. We have only two libs requirement: Protobuf and LevelDB.
plugin: This directory provides the plugin of Logging module. Loggins is an important way to debug a program. But different organazations always implement it in a totally different way. So PhxPaxos does not provide a specific implementation of Logging, instead, it provides the mechanism of Logging so everyone can implement it customly. We also implement a specific Logging by using GLOG for you. If you are using GLOG this may help you in saving your development time.
sample: This directory provides 3 samples based on PhxPaoxs, They representive different depth of using PhxPaxos, from easy to hard.
- PhxElection: This is a very simple program. It implements a Master Election Program by a Master Election state-machine which is embedded in PhxPaxos.
- PhxEcho: This shows how to program a status-machine and combine it with PhxPaxos.
- PhxKV: This is a more complete system. which implements a KV state-machine. It shows how to implement a distributed KV storage system by PhxPaxos and how to delete PaxosLog by implementing the Checkpoint API. It also shows how to combine this code into a RPC(etc: GRPC) framework to get a complete distributed KV storage system.
Guide to Header Files:
- include/node.h The beginning of PhxPaxos. We strongly suggest you to begin here.
- include/options.h Some configurations and options needed while running PhxPaxos.
- include/sm.h A base class of state-machine.
- include/def.h Sets of return code.
- include/network.h Abstract function of Network Module. You can use your own network protocol by overloading these functions.
- include/storage.h Abstract function of Storage Module.
- include/log.h Abstract function of Logging Module.
- include/breakpoint.h Abstract function of breaking points, add your ownMonitor Module here to monitor these break points.
How to Compile
Third party libs preparation
Following is a dependency relationship tablet of all directories.
| Directories | compilation target | inner dependency | third party dependency |
|---|
| root | libphxpaxos.a | None | protobuf,leveldb |
| plugin | libphxpaxos_plugin.a | libphxpaxos.a | glog |
| sample/phxelection | Executable program | libphxpaxos.a,libphxpaxos_plugin.a | None |
| sample/phxecho | Executable program | libphxpaxos.a,libphxpaxos_plugin.a | None |
| sample/phxkv | Executable program | libphxpaxos.a,libphxpaxos_plugin.a | grpc |
| src/ut | Unit tests | None | gtest,gmock |
We only need 2 third party libs: Protobuf and Leveldb while compiling PhxPaxos library(target is libphxpaoxs.a).But we need GLOG and GRPC while compiling other directories. All these third party libs should be prepared and palced in our third_party directory before PhxPaxos compilation. You can git clone them by adding --recurse-submodules on just download and link them.
Compilation Enviroment
Compilation and Installation
How to Complie libphxpaxos.a.
Execute following shell commands in root directory of PhxPaxos
./autoinstall.sh
make
make install
How to Complie libphxpaxos_plugin.a.
Execute following shell commands in plugin directory.
make
make install
How to Wrap Your Own Code Around PhxPaxos.
First choose a single node service.
We will show you this by a PhxEcho service in our sample directory, Echo is a common test functions while writing an RPC service. We will wrap this service's code around PhxPaxos to make Echo into a multi-node service.
First, Assume following is the definition fo PhxEchoServer
class PhxEchoServer
{
public:
PhxEchoServer();
~PhxEchoServer();
int Echo(const std::string & sEchoReqValue, std::string & sEchoRespValue);
};
Let's wrap this code around PhxPaxos.
Second, implement a state-machine
We now define a PhxEchoSM state-machine which inherit from class StateMachine as the following
class PhxEchoSM : public phxpaxos::StateMachine
{
public:
PhxEchoSM();
bool Execute(const int iGroupIdx, const uint64_t llInstanceID,
const std::string & sPaxosValue, phxpaxos::SMCtx * poSMCtx);
const int SMID() const { return 1; }
};
SMID() functions should return an unique identifier since PhxPaxos support more than 1 state-machines at the same time.
Execute() is a state transition function of this state-machine. PhxPaxos guarantees all nodes will execute sPaxosValue in the same order to achieve strong consistency (sPaxosValue is one of input arguments of Execute()). Following is the implementation of this functions:
bool PhxEchoSM :: Execute(const int iGroupIdx, const uint64_t llInstanceID,
const std::string & sPaxosValue, SMCtx * poSMCtx)
{
printf("[SM Execute] ok, smid %d instanceid %lu value %s\n",
SMID(), llInstanceID, sPaxosValue.c_str());
//only commiter node have SMCtx.
if (poSMCtx != nullptr && poSMCtx->m_pCtx != nullptr)
{
PhxEchoSMCtx * poPhxEchoSMCtx = (PhxEchoSMCtx *)poSMCtx->m_pCtx;
poPhxEchoSMCtx->iExecuteRet = 0;
poPhxEchoSMCtx->sEchoRespValue = sPaxosValue;
}
return true;
}
We only print it on the screen as a prove of broadcasting this Echo message.
Here we got a strange class SMCtx, following is the definition.
class SMCtx
{
public:
SMCtx();
SMCtx(const int iSMID, void * pCtx);
int m_iSMID;
void * m_pCtx;
};
SMCtx is a context argument which is provide by proposer(we will offer more details in the following introduction), transmitted to Execute() function by PhxPaxos and finally callback to proposer.
m_iSMID is related to SMID() function mentioned above.PhxPaxos will transmit this to a specific state-machine which owns the same id.
m_pCtx is a customly context point address provided by proposer.
The context arguments of Execute() functions is a nullptr in all nodes except the one which propose it.
Developer should judge if it is NULL while implementing, otherwise it will cause a segment fault.
Following shows the context definition of Echo:
class PhxEchoSMCtx
{
public:
int iExecuteRet;
std::string sEchoRespValue;
PhxEchoSMCtx()
{
iExecuteRet = -1;
}
};
iExecuteRet represents the return code of Execute() execution.
sEchoRespValue represents the sEchoReqValue transmit by Execute().
We finally construct a state-machine and a state transmittion function by classes above.
HINT: What you should do to make a service into a replicated service is to abstract the logic of it. And then implement it in a Execute() fuction. That's all:)
Running PhxPaxos
After the implementation, We will try to run PhxPaxos with PhxEchoSM loaded.
We will do some modifications for EchoServer class first:
class PhxEchoServer
{
public:
PhxEchoServer(const phxpaxos::NodeInfo & oMyNode, const phxpaxos::NodeInfoList & vecNodeList);
~PhxEchoServer();
int RunPaxos();
int Echo(const std::string & sEchoReqValue, std::string & sEchoRespValue);
phxpaxos::NodeInfo m_oMyNode;
phxpaxos::NodeInfoList m_vecNodeList;
phxpaxos::Node * m_poPaxosNode;
PhxEchoSM m_oEchoSM;
};
We add some arguments in construction function, oMyNode represents the information(IP, Port, etc...) of this node.
vecNodeList represents informations of all nodes in this cluster.
These 2 arguments is pre-defined by PhxPaxos.
Except m_oMyNode and m_vecNodeList, m_oEchoSM is a state-machine we just finished, m_poPaxosNode represents the instance pointer of PhxPaxos running this time.
PhxPaxos instance is actived by executing RunPaxos() function, following is the implementation of this function:
int PhxEchoServer :: RunPaxos()
{
Options oOptions;
int ret = MakeLogStoragePath(oOptions.sLogStoragePath);