Writing Converters » History » Version 7

« Previous - Version 7/10 (diff) - Next » - Current version
J. Moringen, 06/26/2011 11:41 PM
minor fix


Writing Converters

Introduction

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 here. However, in many use-cases it is necessary to use additional converters for domain-specific types and/or serialization mechanisms.

This page describes how to add such converters to RSB using the running example of a converter for a fictional SimpleImage data-type.

Warning: this tutorial has been written with simplicity in mind and should not be used as a blueprint for production code. In particular:
  • It does not handle machine Endianess properly
  • It does not handle machine word sizes properly
  • It leaks memory
  • It does not validate any data

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 here for Google protocol buffers.

Preparation

In order to implement a new converter, the following information is required:
  • To/from which wire-type will the converter serialize/deserialize? In our example, the wire-type is an array of bytes (or more formally an array of octets) which is represented in C++ using std::string.
  • Which data-type or (data-types) will be handled by the converter? The struct SimpleImage in our example (please note that this is identified using a string for comparison, not the class itself).
  • What is the wire-schema of the converter? In our example, we use the following ad-hoc wire-schema:
    • Name: simple-image
    • Binary layout: one integer encoding the image width, one integer encoding the image height, width x height bytes for the image data

Implementation: C++

SimpleImage Domain type

The domain data-type is defined in:

source:trunk/cpp/core/examples/custom_converter/SimpleImage.h

SimpleImageConverter Class

For the actual converter implementation, four things are needed:
  1. The C++ representation of the wire-type has to be passed to the Converter interface as a template parameter
  2. The wire-schema and data-type name have to be passed to the Converter constructor
  3. The serialize method has to be implemented
  4. The deserialize method has to be implemented

A naive and incomplete implementation can be found here:

source:trunk/cpp/core/examples/custom_converter/SimpleImageConverter.h
source:trunk/cpp/core/examples/custom_converter/SimpleImageConverter.cpp

Using the Converter

A simple program that demonstrates the use of our SimpleImageConverter can be found in

source:trunk/cpp/core/examples/custom_converter/sender.cpp

A similar program in which the registration of the converter is missing can be found in

source:trunk/cpp/core/examples/custom_converter/senderNoConverter.cpp

This second program servers the purpose of familiarizing you with the "missing-converter" error message, that you will encounter sooner or later ;)