Writing Converters » History » Version 5
J. Moringen, 06/23/2011 08:30 PM
added link to [[ProtocolBufferConverter]]
1 | 1 | J. Moringen | h1. Writing Converters |
---|---|---|---|
2 | 1 | J. Moringen | |
3 | 1 | J. Moringen | h2. Introduction |
4 | 1 | J. Moringen | |
5 | 1 | J. Moringen | In RSB, converters are used to serialize and deserialize programming-language objects for transportation (e.g. over a network connection). RSB comes with converters for the fundamental types listed [[Types|here]]. However, in many use-cases it is necessary to use additional converters for domain-specific types and/or serialization mechanisms. |
6 | 1 | J. Moringen | |
7 | 2 | J. Moringen | This page describes how to add such converters to RSB using the running example of a converter for a fictional @SimpleImage@ [[Glossary|data-type]]. |
8 | 1 | J. Moringen | |
9 | 2 | J. Moringen | *Warning: this tutorial has been written with simplicity in mind and should not be used as a blueprint for production code. In particular:* |
10 | 2 | J. Moringen | * It does not handle machine Endianess properly |
11 | 2 | J. Moringen | * It does not handle machine word sizes properly |
12 | 2 | J. Moringen | * It leaks memory |
13 | 2 | J. Moringen | * It does not validate any data |
14 | 2 | J. Moringen | |
15 | 5 | J. Moringen | In many practical cases, some of these problems (and much of the manual work) can be avoided by using an IDL-specification in combination with code generation and generic converters as described [[ProtocolBufferConverter|here]] for Google protocol buffers. |
16 | 5 | J. Moringen | |
17 | 1 | J. Moringen | h2. Preparation |
18 | 1 | J. Moringen | |
19 | 1 | J. Moringen | In order to implement a new converter, the following information is required: |
20 | 2 | J. Moringen | * To/from which [[Glossary|wire-type]] will the converter serialize/deserialize? In our example, the wire-type is an array of octets which maps to @std::string@ in C++. |
21 | 2 | J. Moringen | * Which [[Glossary|data-type]] or (data-types) will be handled by the converter? The struct @SimpleImage@ in our example. |
22 | 2 | J. Moringen | * What is the [[Glossary|wire-schema]] of the converter? In our example, we use the following ad-hoc wire-schema: |
23 | 2 | J. Moringen | ** Name: @simple-image@ |
24 | 2 | J. Moringen | ** Binary layout: one integer encoding the image width, one integer encoding the image height, width x height bytes for the image data |
25 | 1 | J. Moringen | |
26 | 1 | J. Moringen | h2. Implementation: C++ |
27 | 2 | J. Moringen | |
28 | 2 | J. Moringen | h3. @SimpleImage@ Domain type |
29 | 2 | J. Moringen | |
30 | 3 | J. Moringen | The domain data-type is defined in: |
31 | 1 | J. Moringen | |
32 | 3 | J. Moringen | source:trunk/cpp/core/examples/custom_converter/SimpleImage.h |
33 | 3 | J. Moringen | |
34 | 2 | J. Moringen | h3. @SimpleImageConverter@ Class |
35 | 2 | J. Moringen | |
36 | 2 | J. Moringen | For the actual converter implementation, four things are needed: |
37 | 2 | J. Moringen | # The wire-type has to be passed to the @Converter@ interface as a template parameter |
38 | 2 | J. Moringen | # The wire-schema and data-type name have to be passed to the @Converter@ constructor |
39 | 1 | J. Moringen | # The @serialize@ method has to be implemented |
40 | 1 | J. Moringen | # The @deserialize@ method has to be implemented |
41 | 1 | J. Moringen | |
42 | 3 | J. Moringen | A naive and incomplete implementation can be found here: |
43 | 3 | J. Moringen | |
44 | 3 | J. Moringen | source:trunk/cpp/core/examples/custom_converter/SimpleImageConverter.h |
45 | 3 | J. Moringen | source:trunk/cpp/core/examples/custom_converter/SimpleImageConverter.cpp |
46 | 3 | J. Moringen | |
47 | 3 | J. Moringen | h3. Using the Converter |
48 | 3 | J. Moringen | |
49 | 4 | J. Moringen | A simple program that demonstrates the use of our @SimpleImageConverter@ can be found in |
50 | 3 | J. Moringen | |
51 | 3 | J. Moringen | source:trunk/cpp/core/examples/custom_converter/sender.cpp |
52 | 3 | J. Moringen | |
53 | 3 | J. Moringen | A similar program in which the registration of the converter is missing can be found in |
54 | 3 | J. Moringen | |
55 | 3 | J. Moringen | source:trunk/cpp/core/examples/custom_converter/senderNoConverter.cpp |
56 | 3 | J. Moringen | |
57 | 3 | J. Moringen | This second program servers the purpose of familiarizing you with the "missing-converter" error message, that you will encounter sooner or later ;) |