DOCSEARCHbyAlgolia
Submit Docs

cppzmq Documentation

repository·master·Indexed 25 days ago

https://github.com/zeromq/cppzmq

A lightweight, header-only C++ binding for libzmq that provides type-safe, RAII-style, and exception-based wrappers around the ZeroMQ C API. It requires C++11 and libzmq. The library includes direct mappings in zmq.hpp and higher-level abstractions, such as multipart messaging, in zmq_addon.hpp.

Tokens
1.6K
Snippets
5
Records
8
Agent score
31%

What's inside cppzmq

  1. How cppzmq works and its design goals

    master

    cppzmq is a lightweight, header-only C++ binding for libzmq. It maps the libzmq C API to C++ concepts to provide:

    • Type-safety: Converts void* based C API concepts into typed C++ objects.
    • Exception-based error handling: Replaces errno-based error handling with C++ exceptions.
    • RAII-style resource management: Uses classes to automate the lifecycle of ZeroMQ resources, preventing manual memory/resource leaks.

    Header usage:

    • zmq.hpp: Contains direct mappings of the libzmq C API abstractions.
    • zmq_addon.hpp: Provides additional higher-level abstractions (e.g., multipart messaging).

    Requirements:

    • Requires at least C++11.
    • Requires libzmq to be installed on the system.

  2. Install cppzmq via CMake

    master

    To install cppzmq, you must first ensure libzmq is built and installed.

    1. Build and install libzmq

    git clone https://github.com/zeromq/libzmq.git
cd libzmq
mkdir build
cd build
cmake ..
sudo make -j4 install

    2. Build and install cppzmq

    git clone https://github.com/zeromq/cppzmq.git
cd cppzmq
mkdir build
cd build
# Use -DCPPZMQ_BUILD_TESTS=OFF to skip building tests
cmake ..
sudo make -j4 install
    git clone https://github.com/zeromq/libzmq.git
cd libzmq
mkdir build
cd build
cmake ..
sudo make -j4 install

git clone https://github.com/zeromq/cppzmq.git
cd cppzmq
mkdir build
cd build
cmake ..
sudo make -j4 install

  4. Integrate cppzmq into a CMake project

    master

    Use the provided CMake find package scripts to include the headers and library files. This will also include libzmq for you.

    To link against the shared library:

    find_package(cppzmq)
target_link_libraries(*Your Project Name* cppzmq)

    To link against the static library:

    find_package(cppzmq)
target_link_libraries(*Your Project Name* cppzmq-static)
    #find cppzmq wrapper, installed by make of cppzmq
find_package(cppzmq)
target_link_libraries(*Your Project Name* cppzmq)
# Or use static library to link
target_link_libraries(*Your Project Name* cppzmq-static)

  5. Multipart message exchange over TCP

    master

    This example demonstrates using zmq_addon.hpp to send and receive multi-part messages over TCP. It uses sockopt::last_endpoint to dynamically discover the bound address.

    #include <iostream>
#include <zmq_addon.hpp>

int main()
{
    zmq::context_t ctx;
    zmq::socket_t sock1(ctx, zmq::socket_type::push);
    zmq::socket_t sock2(ctx, zmq::socket_type::pull);
    sock1.bind("tcp://127.0.0.1:*");
    const std::string last_endpoint =
        sock1.get(zmq::sockopt::last_endpoint);
    std::cout << "Connecting to "
              << last_endpoint
              << std::endl;
    sock2.connect(last_endpoint);

    std::array<zmq::const_buffer, 2> send_msgs = {
        zmq::str_buffer("foo"),
        zmq::str_buffer("bar!")
    };
    if (!zmq::send_multipart(sock1, send_msgs))
        return 1;

    std::vector<zmq::message_t> recv_msgs;
    const auto ret = zmq::recv_multipart(
        sock2, std::back_inserter(recv_msgs));
    if (!ret)
        return 1;
    std::cout << "Got " << *ret
              << " messages" << std::endl;
    return 0;
}

  6. Basic ZeroMQ Push example

    master

    A simple example of creating a context, a push socket, binding it to an in-process endpoint, and sending a string buffer.

    #include <zmq.hpp>

int main()
{
    zmq::context_t ctx;
    zmq::socket_t sock(ctx, zmq::socket_type::push);
    sock.bind("inproc://test");
    sock.send(zmq::str_buffer("Hello, world"), zmq::send_flags::dontwait);
}

  7. Reference: cppzmq API types and functions

    master

    The following types and functions are available in zmq.hpp (direct libzmq mappings):

    Types

    • zmq::context_t (class)
    • zmq::ctxopt (enum)
    • zmq::socket_t (class)
    • zmq::socket_ref (class)
    • zmq::socket_type (enum)
    • zmq::sockopt (enum)
    • zmq::send_flags (enum)
    • zmq::recv_flags (enum)
    • zmq::message_t (class)
    • zmq::const_buffer (class)
    • zmq::mutable_buffer (class)
    • zmq::recv_buffer_size (struct)
    • zmq::send_result_t (alias)
    • zmq::recv_result_t (alias)
    • zmq::recv_buffer_result_t (alias)
    • zmq::error_t (class)
    • zmq::monitor_t (class)
    • zmq_event_t (struct)
    • zmq::free_fn (alias)
    • zmq::pollitem_t (alias)
    • zmq::fd_t (alias)
    • zmq::poller_t (class, DRAFT)
    • zmq::event_flags (enum, DRAFT)
    • zmq::poller_event (enum, DRAFT)

    Functions

    • zmq::version()
    • zmq::poll()
    • zmq::proxy()
    • zmq::proxy_steerable()
    • zmq::buffer()
    • zmq::str_buffer()

  8. Reference: zmq_addon.hpp high-level API

    master

    The following types and functions are provided by zmq_addon.hpp for higher-level abstractions:

    Types

    • zmq::multipart_t (class)
    • zmq::active_poller_t (class, DRAFT)

    Functions

    • zmq::recv_multipart()
    • zmq::send_multipart()
    • zmq::send_multipart_n()
    • zmq::encode()
    • zmq::decode()