Header-only C++ binding for libzmq

Overview

CI Coverage Status License

Introduction & Design Goals

cppzmq is a C++ binding for libzmq. It has the following design goals:

  • cppzmq maps the libzmq C API to C++ concepts. In particular:
    • it is type-safe (the libzmq C API exposes various class-like concepts as void*)
    • it provides exception-based error handling (the libzmq C API provides errno-based error handling)
    • it provides RAII-style classes that automate resource management (the libzmq C API requires the user to take care to free resources explicitly)
  • cppzmq is a light-weight, header-only binding. You only need to include the header file zmq.hpp (and maybe zmq_addon.hpp) to use it.
  • zmq.hpp is meant to contain direct mappings of the abstractions provided by the libzmq C API, while zmq_addon.hpp provides additional higher-level abstractions.

There are other C++ bindings for ZeroMQ with different design goals. In particular, none of the following bindings are header-only:

  • zmqpp is a high-level binding to libzmq.
  • czmqpp is a binding based on the high-level czmq API.
  • fbzmq is a binding that integrates with Apache Thrift and provides higher-level abstractions in addition. It requires C++14.

Supported platforms

  • Only a subset of the platforms that are supported by libzmq itself are supported. Some features already require a compiler supporting C++11. In the future, probably all features will require C++11. To build and run the tests, CMake and Catch are required.
  • Any libzmq 4.x version is expected to work. DRAFT features may only work for the most recent tested version. Currently explicitly tested libzmq versions are
    • 4.2.0 (without DRAFT API)
    • 4.3.4 (with and without DRAFT API)
  • Platforms with full support (i.e. CI executing build and tests)
    • Ubuntu 18.04 x64 (with gcc 4.8.5, 5.5.0, 7.5.0)
    • Ubuntu 20.04 x64 (with gcc 9.3.0, 10.3.0 and clang 12)
    • Visual Studio 2017 x64
    • Visual Studio 2019 x64
    • macOS 10.15 (with clang 12, without DRAFT API)
  • Additional platforms that are known to work:
    • We have no current reports on additional platforms that are known to work yet. Please add your platform here. If CI can be provided for them with a cloud-based CI service working with GitHub, you are invited to add CI, and make it possible to be included in the list above.
  • Additional platforms that probably work:
    • Any platform supported by libzmq that provides a sufficiently recent gcc (4.8.1 or newer) or clang (3.4.1 or newer)
    • Visual Studio 2012+ x86/x64

Examples

These examples require at least C++11.

#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);
}

This a more complex example where we send and receive multi-part messages over TCP with a wildcard port.

#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;
}

See the examples directory for more examples. When the project is compiled with tests enabled, each example gets compiled to an executable.

Compatibility Guidelines

The users of cppzmq are expected to follow the guidelines below to ensure not to break when upgrading cppzmq to newer versions (non-exhaustive list):

  • Do not depend on any macros defined in cppzmq unless explicitly declared public here.

The following macros may be used by consumers of cppzmq: CPPZMQ_VERSION, CPPZMQ_VERSION_MAJOR, CPPZMQ_VERSION_MINOR, CPPZMQ_VERSION_PATCH.

Contribution policy

The contribution policy is at: http://rfc.zeromq.org/spec:22

Build instructions

Build steps:

  1. Build libzmq via cmake. This does an out of source build and installs the build files

    • download and unzip the lib, cd to directory
    • mkdir build
    • cd build
    • cmake ..
    • sudo make -j4 install
  2. Build cppzmq via cmake. This does an out of source build and installs the build files

    • download and unzip the lib, cd to directory
    • mkdir build
    • cd build
    • cmake ..
    • sudo make -j4 install

Using this:

A cmake find package scripts is provided for you to easily include this library. Add these lines in your CMakeLists.txt to include the headers and library files of cpp zmq (which will also include libzmq for you).

#find cppzmq wrapper, installed by make of cppzmq
find_package(cppzmq)
target_link_libraries(*Your Project Name* cppzmq)
Comments
  • Overly Aggressive Deprecation Warnings

    Overly Aggressive Deprecation Warnings

    when most of the legacy API calls were deprecated, "valid" (??) code suddenly raises deprecation warnings.

    In particular,

    zmq::message_t msg;        // assume some population
    sock->send(msg);           // raises deprecation warning
    

    This results from

        ZMQ_CPP11_DEPRECATED("from 4.3.1, use send taking message_t and send_flags")
        bool send(message_t &msg_,
                  int flags_ = 0) // default until removed
    
    #ifdef ZMQ_HAS_RVALUE_REFS
        ZMQ_CPP11_DEPRECATED("from 4.3.1, use send taking message_t and send_flags")
        bool send(message_t &&msg_,
                  int flags_ = 0) // default until removed
    

    and

        send_result_t send(const_buffer buf, send_flags flags = send_flags::none)
        send_result_t send(message_t &msg, send_flags flags)
    

    (note the inconsistency between buffer and message_t)

    But if the new API had been given a reasonable default, there would be no need to touch legacy code:

        ZMQ_CPP11_DEPRECATED("from 4.3.1, use send taking message_t and send_flags")
        bool send(message_t &msg_,
                  int flags_); // only when explicitly provided
    #ifdef ZMQ_HAS_RVALUE_REFS
        ZMQ_CPP11_DEPRECATED("from 4.3.1, use send taking message_t and send_flags")
        bool send(message_t &&msg_,
                  int flags_);
    #endif
    
        send_result_t send(const_buffer buf, send_flags flags = send_flags::none)
        send_result_t send(message_t &msg, send_flags flags = send_flags::none)
    

    Of course, there is an API issue where legacy send could return either a bool or a number of bytes (that's bitten me before), and the new API returns a std::optional<size_t> but for that kind of breaking change, it probably would have been better to not overload the function name.

    I realize this change is now quite old (324b11f239511), but maintainers of legacy code are now faced with non-intuitive modifications, when more careful migration planning might have addressed it.

    Note that the conversion of std::optional<T> to bool probably gives the desired results (I haven't thought it completely through), so it's probable that the new API is drop-in replacable. The main point should be to minimize breaking changes. Deprecating "normal" code seems to be contrary to that aim.

    opened by jwmelto 1
  • Call to constructor of 'zmq::message_t' is ambiguous

    Call to constructor of 'zmq::message_t' is ambiguous

    When I use the following code, I encounter an error

    const char* str{"hello"};
    zmq::message_t m{str};
    
    Call to constructor of 'zmq::message_t' is ambiguous
    

    image

    It seems that const string& and string_view are in conflict.

    opened by L-Super 3
  • Rebuild with string_view argument, like the constructor

    Rebuild with string_view argument, like the constructor

    More convenient, like the constructor message_t(std::string_view str)

    This is similar to PR #579 but with std::string_view instead of std::string&.

    opened by Crayon2000 6
  • Compile Error on Apple M1

    Compile Error on Apple M1

    Hi everyone,

    I am trying to compile the example source files under cppzmq-4.9.0/examples however when I run make I get Screen Shot 2022-10-29 at 22 11 04

    In vscode I am able to see methods even though compiler errors about it. What could be the reason for that?

    opened by berkantay 3
  • Crashes under Wine

    Crashes under Wine

    Hi,

    We are using this library in a C++ DLL referenced by a 3rd party windows application. Everything runs fine on Windows, however we need to run it in Linux via Wine.

    When trying to connect to the zeromq remote, the application crashes with the following logs recorded:

    02a8:fixme:secur32:schan_QueryContextAttributesA Unhandled attribute 0x6e 02c4:fixme:secur32:schan_QueryContextAttributesA Unhandled attribute 0x6e 029c:fixme:winsock:WSAIoctl unimplemented ioctl _WSAIOW(IOC_VENDOR, 16) 029c:fixme:winsock:server_ioctl_sock Unsupported ioctl 120348 (device=12 access=0 func=d2 method=0) 029c:fixme:winsock:WSAIoctl unimplemented ioctl _WSAIOW(IOC_VENDOR, 16) 029c:fixme:winsock:server_ioctl_sock Unsupported ioctl 120348 (device=12 access=0 func=d2 method=0) 029c:fixme:winsock:WSAIoctl unimplemented ioctl _WSAIOW(IOC_VENDOR, 16) 029c:fixme:winsock:server_ioctl_sock Unsupported ioctl 120348 (device=12 access=0 func=d2 method=0) 029c:fixme:winsock:WSAIoctl unimplemented ioctl _WSAIOW(IOC_VENDOR, 16) 029c:fixme:winsock:server_ioctl_sock Unsupported ioctl 120348 (device=12 access=0 func=d2 method=0) 029c:fixme:winsock:WSAIoctl unimplemented ioctl _WSAIOW(IOC_VENDOR, 16) 029c:fixme:winsock:server_ioctl_sock Unsupported ioctl 120348 (device=12 access=0 func=d2 method=0) 029c:fixme:winsock:WSAIoctl unimplemented ioctl _WSAIOW(IOC_VENDOR, 16) 029c:fixme:winsock:server_ioctl_sock Unsupported ioctl 120348 (device=12 access=0 func=d2 method=0) Invalid argument (C:\FileShare\Development\vcpkg\buildtrees\zeromq\src\v4.3.4-93 3c603e1e.clean\src\epoll.cpp:187) 029c:fixme:winsock:WSAIoctl unimplemented ioctl _WSAIOW(IOC_VENDOR, 16) 029c:fixme:winsock:server_ioctl_sock Unsupported ioctl 120348 (device=12 access=0 func=d2 method=0) Invalid argument (C:\FileShare\Development\vcpkg\buildtrees\zeromq\src\v4.3.4-93 3c603e1e.clean\src\epoll.cpp:187)

    Is this something that is fixable?

    opened by Greatsamps 1
  • Support for zmq timers?

    Support for zmq timers?

    Hi,

    looking at the library's source, I guess there is no support for timer functions (the ones described in http://api.zeromq.org/master:zmq-timers). Is there a safe way to use zmq timers while continuing to use cppzmq for networking?

    Are there any plans to support them?

    Thanks!

    opened by muxator 1
Releases(v4.9.0)
  • v4.9.0(Oct 9, 2022)

    Changes

    • Type-safe socket.get(sockopt::type) https://github.com/zeromq/cppzmq/pull/523
    • GCC C++14 fix https://github.com/zeromq/cppzmq/pull/553
    • Support ZMQ_ONLY_FIRST_SUBSCRIBE https://github.com/zeromq/cppzmq/pull/558
    • Add pkg-config file and instructions https://github.com/zeromq/cppzmq/pull/564 https://github.com/zeromq/cppzmq/pull/570
    • Fix missing include https://github.com/zeromq/cppzmq/pull/568
    • Fix monitor test failures https://github.com/zeromq/cppzmq/pull/576
    • Improved documentation https://github.com/zeromq/cppzmq/pull/519 https://github.com/zeromq/cppzmq/pull/524
    Source code(tar.gz)
    Source code(zip)
  • v4.8.1(Sep 19, 2021)

  • v4.8.0(Sep 5, 2021)

    Fixed:

    • Fix MSYS libzmq discovery (#510)
    • Fix handshake event don't need DRAFT API in libzmq v4.3.0 and above (#509)
    • Use chrono duration for poll default timeout (#497)
    • context_t close no longer uses deprecated function (#490)
    • Fix for potential memory leak in monitor_t::check_event (#482)
    • Fix if constexpr warnings on MSVC (#460)
    • Fix conversion warnings (#459)
    • Deprecate confusing connected() function (#458)

    Added:

    • Add all draft socket types up to libzmq 4.3.4 (#488)
    • Add support for socket_ref to multipart_t ctor/send/recv (#487, #470)
    • Expose zmq::fd_t (#452)
    • Add poller_t::size function (#451)
    Source code(tar.gz)
    Source code(zip)
  • v4.7.1(Oct 5, 2020)

  • v4.7.0(Sep 30, 2020)

    • Add shutdown() for context_t
    • Typesafe context options
    • Typesafe socket options
    • Better C++ standard detection
    • CMake fixes and improvements
    • Multipart message encoding and decoding
    • Fix (unlikely) UB in message_t constructor
    • Improved poll() overloads
    • Require non-null handlers to active_poller
    • Fix socket move assignment bug
    • Deprecate surprising message_t constructor from string literals
    Source code(tar.gz)
    Source code(zip)
  • v4.6.0(Jan 17, 2020)

    • New generic algorithms for sending and receiving multipart messages
    • New to_string and to_string_view member functions in message_t
    • Less surprising behaviour when move assigning socket_t and context_t
    • Return types for send and recv moved into zmq namespace
    • Checks for 32/64bit-ness in cppzmqConfigVersion.cmake removed
    Source code(tar.gz)
    Source code(zip)
  • v4.5.0(Nov 4, 2019)

  • v4.4.1(Jul 24, 2019)

  • v4.4.0(Jul 24, 2019)

  • v4.3.0(Aug 15, 2018)

    • fixed issues when compiling with C++11
    • fixed and improved cmake build (in and out of source builds, libzmq discovery, fallback to pkg-config and more)
    • updated README.md with clear design goals, supported platforms
    • official CI support for Linux, MacOS and Windows
    • unit tests infrastructure
    • test code coverage brought to 77%
    • updated code style (more details in .clang-format)

    socket_t:

    • added support for draft ZMQ_SERVER and ZMQ_CLIENT sockets
    • added support for draft ZMQ_RADIO and ZMQ_DISH sockets

    poller_t:

    • poller_t became thin abstraction layer on zmq_poller_*
    • functionality with std::function handlers split and moved to a new active_poller_t in zmq_addon.hpp
    • simpler and safer implementation
    • made non-copyable, but properly movable
    • more consistent and robust error handling
    • event type part of handler definition
    • fixed a segfault issue when modifying poller_t from a handler
    • added empty method indicating presence of registered sockets

    context_t:

    • added methods for context options: setctxopt(int option_, int optval_) and int getctxopt(int option_)

    message_t:

    • easier construction from iterable type e.g. std::string, std::array
    • added != and == operators and equals method marked as deprecated

    multipart_t:

    • added an operator<<(std::ostream) to easily print out multipart_t content

    Full list of pull requests merged in this release:

    • [closed] Problem: #209 and monitor_t tests not event driven #255
    • [closed] editing "typename I" to "typename T" due to error: expected nested-na… #250
    • [closed] Add first tests for monitor_t and fix monitor_t::abort #249
    • [closed] Problem: README build badges too generic #248
    • [closed] Problem: Travis requires sudo and draft not enabled for git repo #240
    • [closed] Problem: Coverage with coveralls not working #247
    • [closed] Problem: cmake build succeeds even if libzmq not found #243
    • [closed] Problem: cppzmq build broken with C++11 compiler and git cloned repo. #236
    • [closed] Add message_t::routing_id() and set_routing_id() #235
    • [closed] Problem: cppzmq needs to be installed for pkg-config libzmq #234
    • [closed] Problem: libzmq pkg-config build not covered by CI #232
    • [closed] Problem: OSX build not enabled in Travis #230
    • [closed] Problem: whitespace style too restrictive. #228
    • [closed] Split poller_t into two layers #225
    • [closed] Problem: design goals and supported platforms are not explicitly stated #224
    • [closed] Problem: poller_t::wait_all and active_poller_t::wait declare int ret… #227
    • [closed] Problem: inconsistent code style #226
    • [closed] Problem: client/server socket types not defined. #223
    • [closed] Problem: poller's constructor is not default generated #222
    • [closed] Problem: poller move operations not complete #221
    • [closed] Problem: poller can segfault when modified from registered handler. #219
    • [closed] Fix message using empty version variable #220
    • [closed] Problem: googletest is also installed into install destination #217
    • [closed] Problem: Missing QUIET option causes a CMake warning #218
    • [closed] Problem: deprecated poller's add method in draft API #216
    • [closed] Problem: poller_t does not support modify #215
    • [closed] Problem: Appveyor caches way too much. #214
    • [closed] Problem: Appveyor Windows build does not cache googletest #213
    • [closed] Problem: poller_t's deprecated add might throw std::bad_function_call #211
    • [closed] Problem: Appveyor build is slow. #212
    • [closed] Problem: poller_t invalid behavior on moved sockets #208
    • [closed] Problem: tests are always building #210
    • [closed] Remove unnecessary curly bracket #207
    • [closed] Problem: Windows build broken because of multiple issues #204
    • [closed] Improved tests and implementation of message_t #205
    • [closed] Problem: poller's handler not aware of event type. #200
    • [closed] Problem: message_t could be easier to construct and is missing equal not equal operators #203
    • [closed] Problem: non consistent whitespace formatting #202
    • [closed] Problem: insufficient tests for poller_t, bad usability since caller of add must store function object #201
    • [closed] Problem: poller_t does not have great test coverage #196
    • [closed] Added include directory to CMake instructions #198
    • [closed] Problem: Draft build not enabled for git cloned cppzmq. #195
    • [closed] Add some initial tests, add some build/version CI variants #194
    • [closed] Add basic test infrastructure #192
    • [closed] Add basic Travis CI for cppzmq #191
    • [closed] Fix copy/move constructors of poller_t, and make error handling consistent with rest of API #190
    • [closed] std::string conversion for zmq::message_t #187
    • [closed] Added wrapper for context options #181
    • [closed] fix installation source path of FindZeroMQ.cmake #179
    • [closed] fix updated FindZeroMQ #178
    • [closed] call pkg-config fallback FindZeroMQ.cmake #174
    Source code(tar.gz)
    Source code(zip)
  • v4.2.2(Jul 31, 2017)

    cppzmq version 4.2.2 stable, released on 2017/07/31

    Bug Fixes

    • monitor_t:
      • build error in constructor #135
      • blocked when used without threads #134
      • move constructor was only partly initialized #130
    • socket::send(): improper EHOSTUNREACH handling #125
    • check for zmq_msg_gets did not properly exclude libzmq 4.0.X #114

    Features

    • CMake:
      • export targets to config (requires CMake 3.0+ now) #118 #121
      • pkg-config fallback for libzmq installs via autotools #133
    • peekstr & peektyp: peek into parts of messages #124
    • allow empty handler parameter in zmq::poller_t::add() #119 #120
    • poller_t class based on new libzmq poller API #111

    Misc

    • install instructions added #129 #131
    • Copyright years updated d9f0f016c07046742738c65e1eb84722ae32d7d4
    Source code(tar.gz)
    Source code(zip)
Owner
The ZeroMQ project
The ZeroMQ project
A C++ header-only HTTP/HTTPS server and client library

cpp-httplib A C++11 single-file header-only cross platform HTTP/HTTPS library. It's extremely easy to setup. Just include the httplib.h file in your c

null 8.2k Nov 28, 2022
Header only library for writing build recipes in C.

nobuild Header only library for writing build recipes in C. Main idea The idea is that you should not need anything but a C compiler to build a C proj

Tsoding 104 Oct 25, 2022
modern c++(c++17), cross-platform, header-only, easy to use http framework

cinatra--一个高效易用的c++ http框架 English | 中文 目录 使用cinatra常见问题汇总(FAQ) cinatra简介 如何使用 快速示例 性能测试 注意事项 roadmap 联系方式 cinatra简介 cinatra是一个高性能易用的http框架,它是用modern

qicosmos 1.4k Nov 28, 2022
Brynet - Header Only Cross platform high performance TCP network library using C++ 11.

Brynet Header Only Cross platform high performance TCP network library using C++ 11. Build status Windows : Linux/MacOS : Features Header only Cross p

IronsDu 879 Nov 26, 2022
Header-only, event based, tiny and easy to use libuv wrapper in modern C++ - now available as also shared/static library!

Do you have a question that doesn't require you to open an issue? Join the gitter channel. If you use uvw and you want to say thanks or support the pr

Michele Caini 1.5k Nov 28, 2022
Header-only C++14 library for getting network addresses associated with network interface without name lookups on Windows, macOS, Linux, and FreeBSD

NetIF Get addresses associated with network interfaces on a system without using name lookups. Header-only, requires C++14. Usage Add the header file

GMLC-TDC 9 Oct 17, 2022
Lightweight, header-only, Boost-based socket pool library

Stream-client This is a lightweight, header-only, Boost-based library providing client-side network primitives to easily organize and implement data t

Tinkoff.ru 12 Aug 5, 2022
🥡 Simple header-only RSP server library

librspd Simple header-only, arch-agnostic, RSP server library. What is it about, already ? See https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protoc

Nicolas Sauzede 3 Aug 30, 2022
Netif - Header-only C++14 library for getting network addresses associated with network interface without name lookups on Windows, macOS, Linux, and FreeBSD

NetIF Get addresses associated with network interfaces on a system without using name lookups. Header-only, requires C++14. Usage Add the header file

GMLC-TDC 9 Oct 17, 2022
Asynchronous, Header-only C++ HTTP-over-(TCP|UNIX Socket|STDIO) Library

CXXHTTP A C++ library implementing an asynchronous HTTP server and client. To clone this library, make sure you also clone the submodules. The --recur

null 25 Mar 19, 2021
web server that will print hello world on the screen only for linux users

a simple http server side lib only for linux users Note: This lib is currently under development you can check the source code and even use it but dn'

notaweeb 11 Mar 14, 2021
A simple tcp tunnel on c using sockets Right now it only supports linux systems

A simple tcp tunnel on c using sockets Right now it only supports linux systems build BY MAKE mkdir build make cd build ./tunnel.o <localport> <rem

notaweeb 8 Sep 20, 2021
Tiny HTTP Server on C, using only standard libraries

hell_o Linux only. Tiny HTTP Server on C, using only standard libraries. It is unfinished yet, going to add working interface and rewrite handler late

null 3 Feb 1, 2022
Encapsulates the two protocols of OpenVpn and Ikev2, you only need to enter the server IP and port number to realize the connection and status display, and the specific situation of the connection can be displayed at the same time。

NewVpnCore 封装了OpenVpn和Ikev2两种协议,只需要输入服务器IP和端口号即可实现连接和状态显示,同时可以显示连接的具体情况。 UniteVpn Core(第一版) 1. 模块说明 unitevpn:封装了vpn的操作和统一不同协议信息的模块 ikev2:IKEV2协议的源码 op

ZFashion 3 Jun 8, 2022
A headers only high performance C++ middleware framework/lib. See README for details.

# README # hmbdc is an open source headers only C++ framework and library built on top of various real-world tested lockfree algorithms that facilit

null 15 Nov 6, 2022
A Tcp/Ip stack implementation on top of Solarflare ef_vi, and a C++ headers only framework for tcp multiplexing client/server.

Efvitcp Efvitcp is a tcp library using Solarflare ef_vi interface on linux, and also a tcp multiplexing framework for both C++ client and server progr

Meng Rao 23 Nov 26, 2022
Tinysshd is a minimalistic SSH server which implements only a subset of SSHv2 features

Introduction tinysshd is a minimalistic SSH server which implements only a subset of SSHv2 features. tinysshd supports only secure cryptography (minim

Jan Mojžíš 892 Nov 30, 2022
An extensible, cross-platform, single-header C/C++ OpenGL loader library.

Simple OpenGL Loader An extensible, cross-platform, single-header C/C++ OpenGL loader library. Usage For Windows Win32 or Linux X11 applications, the

Tarek Sherif 79 Oct 19, 2022
single header C(99) library to implement client-server network code for games

single header C(99) library to implement client-server network code for games

Nathan 227 Nov 25, 2022