Generic API publishing techniques - c++

Question

I'm designing the next generation of a framework architecture for an internal project. Essentially there is a run time system that provides an API to applications which can be loaded/unloaded on the fly.
In the framework lives a library of custom "devices" The current interface to these devices is extremely generic; think posix load/unload/read/write/etc... One of the important principles of the framework is that the Apps need to know very little about device specifics.
Unfortunately, this interface has broken down to where the application developers end up rewriting common functions in the application itself.
I'm looking for suggestions or even a place to start reading about designing framework APIs like this. What is a good set of tools that a "device" author in the framework can use to publish an interface? What is the best way to publish an interface?

Answer 1

Ok - a proposal - may be vastly different from what you wanted, but feedback will help home in on something useful.
For synchronous "calls" you want your app module to send an indication of the driver function required and however many arguments, then retrieve some result. That can be achieved in a generic way by have a second, distinct read/write stream over which an encoding of the function and values is transmitted. So, say the driver API includes:
string get_stuff(string x, int y, double d[]);
This is NOT code - it's text that the framework/app can print/parse and potentially use to verify that data is sent and consumed correspondingly.
The app module then writes a "call" to the driver as a stream of function identifier and inputs, followed by a read of the result (assuming the app module has same-named variables holding the desired parameter values).
driver_api << "get_stuff " << escape(x) << ' ' << y << " [" << d.size() << "] ";
for (auto i = d.begin(); i != d.end(); ++i)
driver_api << ' ' << *i;
driver_api << '\n';
std::getline(driver_api, result);
It's a little more work (half an hour?) to create a custom stream wrapper that can wrap driver_api and insert the spaces or other separators/delimiters above, support streaming of containers, and/or send the data in a binary form, letting you write a cleaner and/or faster value-oriented version of the above, something like:
(driver_api << "get_stuff" << x << y << d) >> result;
You could also write normal C++ functions to wrap the above for the app module to call:
string get_stuff(const std::string& x, int y, const std::vector<double>& d)
{
string result;
(driver_api_ << "get_stuff" << x << y << d) >> result;
return result;
}
On the driver side, you'd write matching deserialisation routines to recover the app module specified values from the stream.
For specific architectures you may be able to get libraries to allow more convenient calls to functions, utilising debug information or ABI knowledge etc, whereas the above only needs Standard C++ and can be written to be portable (with a little care if doing binary serialisation of endian values).
EDIT - example of binary serialisation (just output for now / runs but output not carefully inspected for validity / most things fixed-width but strings are NUL terminated and containers prefixed by size / doesn't send following-field type information but very easy to create a version that does):
#include <iostream>
#include <vector>
#include <winsock2.h>
typedef signed char int8_t;
typedef signed short int16_t;
typedef signed int32_t;
typedef unsigned char uint8_t;
typedef unsigned short uint16_t;
typedef unsigned uint32_t;
class Binary_IOStream
{
public:
Binary_IOStream(std::istream& i, std::ostream& s) : i_(i), s_(s) { }
typedef Binary_IOStream This;
This& operator<<(int8_t x) { return write(x); }
This& operator<<(int16_t x) { return write(htons(x)); }
This& operator<<(int32_t x) { return write(htonl(x)); }
This& operator<<(uint8_t x) { return write(x); }
This& operator<<(uint16_t x) { return write(htons(x)); }
This& operator<<(uint32_t x) { return write(htonl(x)); }
This& operator<<(const std::string& s)
{ s_.write(s.c_str(), s.size() + 1); // include NUL, but could size-prefix
return *this; }
This& operator<<(double x) { return write(x); }
template <typename T>
This& operator<<(const std::vector<T>& v)
{ return write_range(v.begin(), v.end()); }
template <typename Iterator>
This& write_range(Iterator begin, Iterator end)
{
operator<<(std::distance(begin, end));
while (begin != end)
operator<<(*begin++);
return *this;
}
private:
template <typename T>
This& write(const T& t)
{ s_.write((const char*)&t, sizeof t); return *this; }
std::istream& i_;
std::ostream& s_;
};
int main()
{
Binary_IOStream bs(std::cin, std::cout);
bs << ('A' << 24) + ('b' << 16) + ('c' << 8) + 'D';
bs << "hello world!";
std::vector<double> v;
v.push_back(3.14);
v.push_back(2.72);
bs << v;
}