Custom network module

Tacopie

tacopie is a C++11 TCP Client library used by default by cpp_redis to make it easy to test and develop a software communicating with a Redis server using cpp_redis.

However, tacopie might not fulfill the needs of everyone: some people already use another networking library for other features or are looking for some feature not supported by tacopie.

To solve this issue, tacopie is not a mandatory dependency but is only provided as-is for convenience. The developer is free to use any other networking library by following the steps listed above.

Only asynchronous TCP clients are supported. No support for synchronous clients is planned.

Setting-Up your custom library

CMake USE_CUSTOM_TCP_CLIENT

First, you have to compile with the USE_CUSTOM_TCP_CLIENT CMake variable. This CMake variable will make cpp_redis compile in a special configuration allowing you to use the library of your choice.

Provide implementation for tcp_client_iface

cpp_redis defines the tcp_client_iface interface in cpp_redis/network/tcp_client_iface.hpp.

You must provide an implementation for this interface by creating your own class inheriting from cpp_redis::network::tcp_client_iface and implementing the following methods:

connect

virtual void connect(const std::string& addr, std::uint32_t port) = 0;

Connect the TCP client to the given host and port.

disconnect

virtual void disconnect(bool wait_for_removal = false) = 0;

Disconnect the TCP client.

If wait_for_removal is set to true, disconnect blocks until the underlying TCP client has been effectively removed from the io_service (if any) and that all the underlying callbacks have completed.

is_connected

virtual bool is_connected(void) const = 0;

Returns whether the client is connected or not.

async_read

virtual void async_read(read_request& request)   = 0;

Takes as parameter a read_request and process a read operation asynchronously.

read_request is defined as follow:

//! structure to store read requests information
struct read_request {
  std::size_t size;
  async_read_callback_t async_read_callback;
};

where:

• size is the number of bytes to read
• async_read_callback is the callback to be executed on read completion

async_read_callback is defined as follow:

typedef std::function<void(read_result&)> async_read_callback_t;

where read_result is defined as follow:

//! structure to store read requests result
struct read_result {
  bool success;
  std::vector<char> buffer;
};

where:

• success is whether the operation was successful or not
• buffer contains the read bytes

async_write

virtual void async_write(write_request& request) = 0;

Takes as parameter a write_request and process a write operation asynchronously.

write_request is defined as follow:

//! structure to store write requests information
struct write_request {
  std::vector<char> buffer;
  async_write_callback_t async_write_callback;
};

where:

• buffer contains the bytes to be written
• async_write_callback is the callback to be executed on write completion

async_write_callback is defined as follow:

typedef std::function<void(write_result&)> async_write_callback_t;

where write_result is defined as follow:

//! structure to store write requests result
struct write_result {
  bool success;
  std::size_t size;
};

where:

• success is whether the operation was successful or not
• size contains the number of bytes written

Use your custom TCP client with cpp_redis

The last step is to simply use the tcp_client you just have just created with cpp_redis.

When compiling with USE_CUSTOM_TCP_CLIENT, the default constructors of redis_client, redis_subscriber, future_client are disabled and you must you another constructor instead:

• redis_client

explicit redis_client(const std::shared_ptr<network::tcp_client_iface>& tcp_client);

• redis_subscriber

explicit redis_subscriber(const std::shared_ptr<network::tcp_client_iface>& tcp_client);

• future_client

explicit future_client(const std::shared_ptr<network::tcp_client_iface>& tcp_client);

Each of these constructors simply takes a shared_ptr to a tcp_client_iface to be initialized: simply pass in a shared_ptr to your custom TCP client.

That's it, you are all set and can start using cpp_redis with your chosen TCP client library!