Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pearu/simple-rpc-cpp
a simple RPC wrapper generator to C/C++ functions
https://github.com/pearu/simple-rpc-cpp
Last synced: 4 days ago
JSON representation
a simple RPC wrapper generator to C/C++ functions
- Host: GitHub
- URL: https://github.com/pearu/simple-rpc-cpp
- Owner: pearu
- Created: 2015-08-05T12:19:42.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2015-08-05T12:50:44.000Z (over 9 years ago)
- Last Synced: 2024-11-01T09:42:55.437Z (11 days ago)
- Language: Python
- Homepage:
- Size: 164 KB
- Stars: 37
- Watchers: 5
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
This project initiated from the following practical problem. To control experimental equipment via computers, manufactures provide software drivers with SDK written in C/C++. Unfortunately, Windows platform is often the only supported platform or support for other platforms stays years behind. In order to control such equipment from a Linux platform, for instance, Remote Procedure Calling (RPC) techniques can be used.
_Simple RPC C++_ project provides a Python script that generates wrappers to C/C++ functions and RPC server applications so that the wrapped C/C++ functions could be called from an application (local host) but the C/C++ functions are executed on a server application (remote host).
The usage of word "simple" in the name of this project is due to the following:
* _RPC technology can be simple to use_ --- editing existing code should be minimal in order to remotely call C/C++ functions. Just changing the name of a header file should be sufficient to adapt an application to use RPC for certain C/C++ functions. Note that existing RPC libraries require RPC specific client applications; the current project aims at requiring minimal modification to client applications so that switching from calling C/C++ functions directly or via RPC, would be straightforward.
* _Simplification can be sufficient for practical applications_ --- C/C++ functions that can be wrapped for RPC, are assumed to have "simple" prototypes, that is, the arguments should have types that Boost serialization library can handle. This includes all standard C/C++ scalar types and standard STL collections. These types can be defined in arguments as is, or as references, or as pointers. Notice that pointer arguments are treated in application program (in local host) as scalars that can be passed to RPC server program where they point to actual memory location of the remote host.
* _Simplicity goes with restrictions_ --- For instance, wrapping C++ template functions is not supported. In addition, when running an application and RPC server on hosts with different architecture or operating system, special care must be taken to ensure that the data exchange between local and remote host is correct. For instance, the size of standard C/C++ `int` type may be different on local and remote hosts leading to possible corruption of data. To avoid this, always use scalar types with fixed byte width, for instance, `int32_t`, `uint64_t`, etc. Finally, no care is taken when the endian of local and remote hosts differ..
# Installation #
The project assumes availability of Python 2.x. Python 3.x support might require minor modifications in the project source code, patches are welcome.
Checkout the project source code, see [Source/Checkout](https://code.google.com/p/simple-rpc-cpp/source/checkout) for instructions. In the source code directory, run
```
sudo python setup.py install
```
Windows users should run `python setup.py install` from command prompt.To verify success, execute
```
cd tests
make
```
If the tests pass, you can try out the "Example" project below.# Example #
A typical C/C++ project consists of three parts: application source file containing the `main` function, source file(s) of computational functions, and header file(s) of the corresponding prototypes.
All source files are compiled and linked together resulting an application program.
When running this application program, the `main` function calls computational functions
and outputs the results. Our aim is that when `main` function calls computational functions then they are actually executed in remote host. For that we use RPC technique to send function arguments and then receive function results over network. The current project _Simple RPC C++_ provides a Python script `simple_rpc` that constructs RPC wrapper functions to computational functions and generates the corresponding RPC source code. By design, modifications to existing source files are minimal.
In fact, in a typical usage case only the application source file requires minor editing while no modifications are needed to the rest of source or header files, as will be demonstrated below.To illustrate this, consider the following example project consisting of three files:
Source file: example_dot.cpp
Header file: example_dot.hpp
Application source file: example_dot_app.cpp#include "example_dot.hpp"
double dot_product(const vector<double> & a,
const vector<double> & b
)
{
double sum = 0;
for (int i = 0; i < a.size(); i++)
sum += a[i] * b[i];
return sum;
}
#ifndef EXAMPLE_DOT_HPP_DEFINED
#define EXAMPLE_DOT_HPP_DEFINED
#include <vector>
using namespace std;
double dot_product(const vector<double> & a,
const vector<double> & b
);
#endif
#include <iostream>
#include "example_dot.hpp"
main()
{
vector<double> a(3);
a[0] = 1.2; a[1] = 3.4; a[2] = 5.6;
cout << "dot_product(a,a) -> ";
cout << dot_product(a,a) << endl;
}
The corresponding application can be compiled and executed:
```
$ c++ example_dot.cpp example_dot_app.cpp -o example_dot_app
$ ./example_dot_app
dot_product(a,a) -> 44.36
```In order to call `dot_product` via RPC server, first, we generate wrapper codes:
```
$ simple_rpc example_dot.hpp
Creating RPC wrappers to functions:
double dot_product(const vector & a,
const vector & b
)
creating file example_dot-rpc.hpp
creating file example_dot-rpc.cpp
creating file example_dot-rpc-server.cpp
```
Notice that the `simple_rpc` script takes header files for input and generates
three files as shown above. These files will be used to compile and build two
executable programs: one for application and one for RPC server.Next, we will modify the application source code as follows.
Source file: example_dot.cpp
Header file: example_dot.hpp
Application source file: example_dot_app.cpp#include "example_dot.hpp"
double dot_product(const vector<double> & a,
const vector<double> & b
)
{
double sum = 0;
for (int i = 0; i < a.size(); i++)
sum += a[i] * b[i];
return sum;
}
#ifndef EXAMPLE_DOT_HPP_DEFINED
#define EXAMPLE_DOT_HPP_DEFINED
#include <vector>
using namespace std;
double dot_product(const vector<double> & a,
const vector<double> & b
);
#endif
#include <iostream>
#include "example_dot-rpc.hpp" // <-- (1)
#ifdef SimpleRPC // <-- (2)
using namespace simple_rpc::example_dot; // <-- (2)
#endif // <-- (2)
main()
{
SIMPLE_RPC_CONNECT("127.0.0.1", 2340, 2); // <-- (3)
vector<double> a(3);
a[0] = 1.2; a[1] = 3.4; a[2] = 5.6;
cout << "dot_product(a,a) -> ";
cout << dot_product(a,a) << endl;
}
The application source code is modified in three places indicated with `// <-- (#)`:
1. The name of the header file is appended with `-rpc` suffix. The generated header file contains RPC wrapper functions to functions found in the original header file.
1. `ifdef SimpleRPC` block is inserted. This is done for convenience as it will make easy to disable (use `-DDISABLE_SIMPLE_RPC` when compiling application code) and enable RPC in the application code. Following `using namespace` declaration exposes the RPC wrapper of `compute_dot` function to current namespace. In general, RPC wrappers are defined in namespace `simple_rpc::`.
1. `SIMPLE_RPC_CONNECT` macro is used to specify the RPC server host IP, port number and debug level (0 means no debug messages are shown, increasing this number will increase verbosity). Here we use debug level 2 in order to illustrate the connection between the application code and RPC server, see below.Next, the application and the RPC server programs must be built. In the given example
we use RPC server local host (the corresponding host IP is 127.0.0.1) but, in general,
the application program must be built on local host while the RPC server program on
server host, especially, if these hosts run different operating systems.
The following table illustrates the build process:Remote host
Local host$ c++ example_dot.cpp example_dot-rpc-server.cpp \
-o example_dot-rpc-server -pthread \
-lboost_system -lboost_serialization \
-I`simple_rpc --include-dir`
$ c++ example_dot-rpc.cpp example_dot_app.cpp \
-o example_dot_app-rpc -pthread \
-lboost_system -lboost_serialization \
-I`simple_rpc --include-dir`
Notice that all source codes of functions must be compiled on remote host while the application source code with RPC wrapper source is compiled on local host.
Finally, we run the RPC server in remote host, and subsequently, run the application program:
Remote host
Local host$ ./example_dot-rpc-server
rpc-server[2] waits connection via port 2340...connected!
rpc-server:read_scalar<j>(a.size) <- 4 bytes
rpc-server:read_vector<d>(a) <- 24 bytes
rpc-server:read_scalar<j>(b.size) <- 4 bytes
rpc-server:read_vector<d>(b) <- 24 bytes
rpc-server:write_buffer_list(dot_product(a, b)) -> 16 bytes
rpc-server[3] waits connection via port 2340...
$ ./example_dot_app-rpc
set_debug_level:write_buffer_list(set_debug_level(debug_level)) -> 4 bytes
dot_product:write_buffer_list(dot_product(a, b)) -> 56 bytes
dot_product:read_scalar<d>(return_value) <- 8 bytes
dot_product(a,a) -> 44.36
Notice that RPC server can run continuously and different application programs can
execute functions from the server. This will work only when different application
programs will not execute the server functions at the same time. Server will serve the first application and during the time of execution, connections to the server by other applications will be declined.