README.md

   1 # Pxp RPC
   2
   3 ### Introduce
   4
   5 PxpRpc(pursuer cross platform remote procedure call) is a very tiny rpc library aim to call and interchange data cross platform and language with high performance and little load.
   6
   7 Currently , This project is in early state, and implemented on below platform
   8
   9 rpc server on java (>=1.6)
  10
  11 rpc server on c
  12
  13 rpc server over tcp on c with tbox
  14
  15 rpc server and client on python(>=3.8)
  16
  17 rpc client on typescript(websocket)
  18
  19
  20
  21 ### rpc message format
  22
  23 The rpc message format is defined like below.
  24
  25
  26 ```c
  27
  28 #include <stdint.h>
  29
  30 #pragma pack(1)
  31
  32 //function:push (push bytes data to server and put the reference into slot addressed by dest_addr.)
  33 //Explain in C, *dest_addr=&data
  34 struct push_request{
  35     struct{
  36         uint8_t opcode;  // "opcode" identify the type of the request. for push_request,this value is 1
  37         uint8_t id1;
  38         uint16_t id2;
  39     } session;   /* "session" is an identifier established by the client.
  40         The Server MUST reply "session" with the same value in the Response struct for ALL request types */
  41
  42     uint32_t dest_addr;
  43     uint32_t length;
  44     char data[length];
  45 };
  46 struct push_response{
  47     struct{
  48         uint8_t opcode;  // 1
  49         uint8_t id1;
  50         uint16_t id2;
  51     } session;  // MUST be the same as the value of "session" in request
  52 };
  53
  54 //function:pull (pull bytes data refered by the reference in slot addressed by src_addr.)
  55 //Explain in C, return **src_addr
  56 struct pull_request{
  57     struct{
  58         uint8_t opcode;  // 2
  59         uint8_t id1;
  60         uint16_t id2;
  61     } session;
  62     uint32_t src_addr;
  63 };
  64 struct pull_response{
  65     struct{
  66         uint8_t opcode;  // 2
  67         uint8_t id1;
  68         uint16_t id2;
  69     } session;
  70
  71     uint32_t length; // 0XFFFFFFFF(-1) if data can't be transfered,In this case, sizeof(data)==0
  72     char data[length];
  73 };
  74 //function:assign (set slot value.)
  75 //Explain in C, *dest_addr=*src_addr
  76 struct assign_request{
  77     struct{
  78         uint8_t opcode;  // 3
  79         uint8_t id1;
  80         uint16_t id2;
  81     } session;
  82     uint32_t dest_addr;
  83     uint32_t src_addr;
  84 };
  85 struct assign_response{
  86     struct{
  87         uint8_t opcode;  // 3
  88         uint8_t id1;
  89         uint16_t id2;
  90     } session;
  91 };
  92
  93 //function:unlink (set slot to NULL.)
  94 // Explain in C, *dest_addr=NULL
  95 //server may decide if the resources can be free.
  96 struct unlink_request{
  97     struct{
  98         uint8_t opcode;  // 4
  99         uint8_t id1;
 100         uint16_t id2;
 101     } session;
 102     uint32_t dest_addr;
 103 };
 104 struct unlink_response{
 105     struct{
 106         uint8_t opcode;  // 4
 107         uint8_t id1;
 108         uint16_t id2;
 109     } session;
 110 };
 111
 112 //function:call (invoke function stored in func_addr.)
 113 //Explain in C, *dest_addr=(*func_addr)(param1,param2...)
 114 //PxpRpc assume the client always know the definition of the function.
 115 //So wrong parameter may BREAK the PxpRpc connection permanently.
 116 struct call_request{
 117     struct{
 118         uint8_t opcode;  // 5
 119         uint8_t id1;
 120         uint16_t id2;
 121     } session;
 122     uint32_t dest_addr;
 123     uint32_t func_addr;
 124     //parameter
 125     uint32_t param1;
 126     uint64_t param2;
 127     uint32_t etc;
 128 };
 129 struct call_response{
 130     struct{
 131         uint8_t opcode;  // 5
 132         uint8_t id1;
 133         uint16_t id2;
 134     } session;
 135     #if FUNCTION_RETURN_32BIT
 136     //function return boolean,int8-int32,float32,object slot address
 137     uint32_t returnValue;
 138     #elif FUNCTION_RETURN_64BIT
 139     //funcion return int64,float64
 140     uint64_t returnValue;
 141     #endif
 142 };
 143
 144 //function:getFunc (get builtin function named by string refered by func_name_addr.)
 145 //Explain in C,*dest_addr=getFunction(*func_name_addr)
 146 //func_name_addr can be a slot where stored the reference to a utf8 encode string pushed previously.
 147 struct getFunc_request{
 148     struct{
 149         uint8_t opcode;  // 6
 150         uint8_t id1;
 151         uint16_t id2;
 152     } session;
 153     uint32_t dest_addr;
 154     uint32_t func_name_addr;
 155 };
 156 struct getFunc_response{
 157     struct{
 158         uint8_t opcode;  // 6
 159         uint8_t id1;
 160         uint16_t id2;
 161     } session;
 162     uint32_t dest_addr; // 0 if function not found
 163 };
 164
 165 //function:close (free the resource and prepare to disconnect)
 166 struct close_request{
 167     struct{
 168         uint8_t opcode;  // 7
 169         uint8_t id1;
 170         uint16_t id2;
 171     } session;
 172 };
 173 //closed, No response.
 174
 175 //function:getInfo (get string encoded in utf8 indicate the information about the server.)
 176 struct getInfo_request{
 177     struct{
 178         uint8_t opcode;  // 8
 179         uint8_t id1;
 180         uint16_t id2;
 181     } session;
 182 };
 183 struct getInfo_response{
 184     struct{
 185         uint8_t opcode;  // 8
 186         uint8_t id1;
 187         uint16_t id2;
 188     } session;
 189     uint32_t length; // 0XFFFFFFFF(-1) if data can't be transfered,In this case, sizeof(data)==0
 190     char data[length];
 191 };
 192 /*
 193 "data" stored the information about the server (as utf8). An example "data" show below
 194 -----------------------------
 195 server name:pxprpc for java
 196 version:1.0
 197 reference slots size:256
 198 -------------------------------
 199 "server name" indicate the server name.
 200 "version" indicate the pxprpc protocol version. Currently only 1.0 is valid.
 201 "reference slots capacity" indicate how many slots can client use. Client should ensure that the slot address is less than this value.
 202 */
 203
 204 /*
 205 the server should take responsibility for the lifecycle manager of the objects referred by references slots.
 206 When an object have no reference refer to, server should free it.
 207 */
 208 ```
 209
 210
 211
 212 See java test file for detail usage.
 213
 214 Feel free to PR and issue
 215