Skip to content
This repository
tree: 4ca7bb1a72
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 178 lines (140 sloc) 7.028 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177
------------------------------------
Thrift Server Generator
a.k.a. "fills in the blanks for you"
------------------------------------
(c) 2011 Elias Karakoulakis <elias.karakoulakis@gmail.com>

Requirements:
-------------
    Apache Thrift >= 0.7.0
    Ruby >= 1.9.1
    RbGCCXML (http://rbplusplus.rubyforge.org/rbgccxml/) >= 1.0.2

About the script:
-----------------
When I learned about Thrift, I immediately fell in love with it: it made RPC
almost "transparent", like the way I imagined it, and best of all, crossing
most programming languages barriers with ease!

What it lacks though is the "sauce" that binds it to your infrastructure,
and when you have a 100+ methods C++ API to begin with, it is awkward
that you still need to write the server code all by yourself.

This little script is a nice complement to Apache Thrift. All it does is to parse
two sets of files: 1) the C++ server skeleton file produced by Thrift, and
2) the headers of the C++ library you want to expose with Thrift.
It uses the excellent tool "RbGCCXML" to build an XML-like tree of the two
interfaces and binds them together (*ahem* at least it tries to).

So say you want to expose your shiny app/lib to the world. Only problem is
it's API is of monstrous size (hundreds of methods) and you need it quick.
Use this script and you can have the skeleton file automatically generate
the actual server code for Thrift. And, if you're lucky (and the library's
API is consistent), you even might compile it without errors!

For example, OpenZWave has a single "Manager" class for interfacing with
the rest of the world, as shown below (comments stripped for brevity)

namespace OpenZWave {
    class Manager {
        bool isPolled( ValueID const _valueId );
        void SetPollInterval( int32 _seconds );
        string GetNodeType( uint32 const _homeId, uint8 const _nodeId );
        ... etc
    }
}

You can declare all the API as a Thrift IDL file:

service RemoteManager {
    bool isPolled( 1:RemoteValueID _valueId );
    void SetPollInterval( 1:i32 _seconds );
    string GetNodeType( 1:i32 _homeId, 2:byte _nodeId );
    ...
}

Then you configure & run the script:

ekarak@ekarak-laptop:~/ozw/thrift4ozw$ ruby1.9.1 create_server.rb
CREATING MAPPING for (bool) IsPrimaryController
tgt=::uint32 const _homeId, src=RemoteManagerHandler::IsPrimaryController::_homeId
...tons

the resulting code tries to map functions (including overloaded ones) from
the Thrift skeleton file into the realm of the existing library, so that:

  bool IsPrimaryController(const int32_t _homeId) {
    // Your implementation goes here
    printf("IsPrimaryController\n");
  }

turns into:

  bool IsPrimaryController(const int32_t _homeId) {
Manager* mgr = Manager::Get();
g_criticalSection.lock();
bool function_result = mgr->IsPrimaryController((::uint32 const) _homeId);
g_criticalSection.unlock();
return(function_result);
  }

The critical section is needed to serialize access to OZW from the thrift
server's thread. Got it? S&S (silly and simple....)

The produced C++ server file will probably still need some manual tweaking,
but that's up to the quality of the library's API. In my case (the OpenZWave
library), I only had to write some 15 lines of extra code for 3 methods with
"peculiar" arguments, like iterating over a pointer array to fill in a std::vector

For instance, there's the "Manager::GetNodeNeighbors" method:
(uint32 GetNodeNeighbors( uint32 const _homeId, uint8 const _nodeId, uint8** _nodeNeighbors );

Look at the last argument: am I dreaming?? a double star in C++??
The method is a C-style call to get a bitmap of node neighbors, its return
value is the size of the array pointed by _nodeNeighbors. If the map is
empty, you don't need to delete the map (so does the OpenZWave API say)
Its thrift IDL is:

struct UInt32_ListByte {
    1:i32 retval;
    2:list<byte> _nodeNeighbors;
}
UInt32_ListByte GetNodeNeighbors( 1:i32 _homeId, 2:byte _nodeId);

And the produced Thrift server code for C++ is:

  void GetNodeNeighbors(UInt32_ListByte& _return, const int32_t _homeId, const int8_t _nodeId) {
Manager* mgr = Manager::Get();
g_criticalSection.lock();
_return.retval = mgr->GetNodeNeighbors((::uint32 const) _homeId, (::uint8 const) _nodeId, (::uint8**) &_return._nodeNeighbors); // ERROR, vector<uint8> is not uint8**
g_criticalSection.unlock();
  }

The create_server.rb script tried to cast a vector<uint8> to the _nodeNeighbors
argument but this will coredump your executable because the method is
expecting a plain-old C-style pointer to an array of uint8. Alas, you have to
manually write a simple iterator:

  void GetNodeNeighbors(UInt32_ListByte& _return, const int32_t _homeId, const int8_t _nodeId) {
      uint8* arr;
Manager* mgr = Manager::Get();
g_criticalSection.lock();
_return.retval = mgr->GetNodeNeighbors((::uint32 const) _homeId, (::uint8 const) _nodeId, (::uint8**) &arr);
g_criticalSection.unlock();
    if (_return.retval > 0) {
        for (int i=0; i<_return.retval; i++) _return._nodeNeighbors.push_back(arr[i]);
        delete arr;
    }
  }



1) The rough requirements are:
-----------------------------------------------
Use a universal naming conversion using the underscore('_') for overloaded
functions and datatypes. For instance, these OpenZWave::Manager overloaded
methods ("GetValueListSelection") must be declared in Thrift as:

    //(c++) bool GetValueListSelection( ValueID const& _id, int32* o_value );
    Bool_String GetValueListSelection_String( 1:RemoteValueID _id );

    //(c++) bool GetValueListSelection( ValueID const& _id, int32* o_value );
    Bool_Int GetValueListSelection_Int32( 1:RemoteValueID _id );

This example illustrates the use of underscore in both intended cases:
- the function return struct (since there are two values we need to get them
returned)
- the function overloading mechanism (since Thrift doesn't support
overloading by its own)

Bool_xxxxx is a simple struct with TWO members:
  1: bool retval = the function's result value (bool in our case)
  2: (string/i32) arg = the last argument, passed as a pointer
(*FIXME* possible memory leak here!)

The Thrift function naming scheme maps these two functions as:
  void GetValueListSelection_String(Bool_String& _return, const RemoteValueID _id)
  void GetValueListSelection_Int32(Bool_Int& _return, const RemoteValueID _id)

And the script's generated code for these two methods is:

  void GetValueListSelection_String(Bool_String& _return, const RemoteValueID _id) {
Manager* mgr = Manager::Get();
g_criticalSection.lock();
_return.retval = mgr->GetValueListSelection(*g_values[_id], (std::string*) &_return.arg);
g_criticalSection.unlock();
  }

  void GetValueListSelection_Int32(Bool_Int& _return, const RemoteValueID _id) {
Manager* mgr = Manager::Get();
g_criticalSection.lock();
_return.retval = mgr->GetValueListSelection(*g_values[_id], (::int32*) &_return.arg);
g_criticalSection.unlock();
  }


December 2011,
Elias Karakoulakis
Something went wrong with that request. Please try again.