Packeteer provides a simplified, asynchronous, event-based socket API.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
Jens Finkhaeuser f58fa75f17
Add logo
15 hours ago
benchmarks Update/fix copyright notice in code files 3 weeks ago
changelog.d Boilerplate for towncrier & changelog entry 1 month ago
data Change build scripts from autotools to cmake (first cut) 5 years ago
docs Add logo 15 hours ago
examples Update/fix copyright notice in code files 3 weeks ago
ext Update/fix copyright notice in code files 3 weeks ago
include Update/fix copyright notice in code files 3 weeks ago
lib Update/fix copyright notice in code files 3 weeks ago
scripts For #26, prepare an update to appveyor scripts 2 months ago
subprojects For #26, update subprojects 2 months ago
test Update/fix copyright notice in code files 3 weeks ago
util Update/fix copyright notice in code files 3 weeks ago
.appveyor.yml #26: ignore util tests on windows as long as the scheduler isn't 100% 2 months ago
.appveyor_account.yml For #26, prepare an update to appveyor scripts 2 months ago
.gitignore For #26, update Pipfile{.lock} 2 months ago
.oclint Add oclint target + configuration 2 years ago
.semgrepignore Update copyright notice; there was an error 4 weeks ago
.woodpecker.yml CI images should be latest 1 month ago
AUTHORS.md Change build scripts from autotools to cmake (first cut) 5 years ago
CODE_OF_CONDUCT.md Add CoC, DCO, and CONTRIBUTING document, which also provides the 2 years ago
CONTRIBUTING.md Update copyright notice; there was an error 4 weeks ago
DCO.txt Add CoC, DCO, and CONTRIBUTING document, which also provides the 2 years ago
LICENSE Bring license in line with OSI/FSF specs 10 months ago
Pipfile Update contributing documentation, Pipfile sections 1 month ago
Pipfile.lock Update contributing documentation, Pipfile sections 1 month ago
README.md Add logo 15 hours ago
build-config.h.in Simplify error formatting; this is now in liberate 2 years ago
meson.build #26: update meson.build (WIP?) 2 months ago
meson_options.txt Add default for detected hardware concurrency to build options 2 years ago
towncrier.toml Boilerplate for towncrier & changelog entry 1 month ago

README.md

Overview

status-badge Build status

Packeteer provides a cross-platform socket API in C++.

The aim of the project is to get high performance, asynchronous inter-process I/O into any project without the need for a ton of external libraries, or for writing cross-platform boilerplate.

Packeteer achieves this aim by:

  • Picking the best available event notification for the target system.
  • and providing a socket-like API for supported IPC.

The project was started a long time ago, but was not public until recently. Some of the code has been extensively used in commercial products.

Quick Start

You can browse the examples folder for an echo server and client implementation, each in ~100 lines of code. The gist, however, is this:

  1. Create a connector, which provides the socket-like API:
    auto conn = packeteer::connector{api, "tcp://192.168.0.1:4321"};
    auto err = conn.connect();
    
  2. If a server was listening on the given address and port, you can now start with I/O:
    size_t transferred = 0;
    err = conn.write(buf, buflen, transferred);
    err = conn.read(buf, buflen, transferred);
    
    This, of course, can fail if there is no data to transfer.
  3. Asynchronous I/O is achieved by registering callbacks for I/O events with a scheduler object.
    using namespace packeteer;
    auto sched = scheduler{api};
    sched.register_connector(PEV_IO_READ, conn,
        [*](time_point const & now, events_t events, connector * the_conn) -> error_t
        {
           // Is notified when the given connector is readable.
           the_conn->read(buf, buflen, transferred);
        }
     );
    
  4. The rest of the echoserver and echoclient implementations are taken up by asynchronously accepting connections and error handling.

Additional Things

The basics of packeteer are covered by the quick start above. However, there are optional additions to the library.

  • ext contains extensions to packteer in the form of optional connectors that may not be available on all platforms.
  • util contains utility functionality; optional code that helps in developing applications without being strictly necessary.

Building

Requirements

  • meson for the build system. Meson is most easily installed via python's pip tool. Installing Python als means you can use the android.py script for Android builds.
  • ninja or platform-specific tools for build execution.
  • Packeteer is implemented in C++, and requires some compiler support for the C++17 standard.
  • Depending on which scheduler implementation you want to use, packeteer may require specific OS and kernel versions, e.g. Linux 2.6.9+ for the epoll scheduler, etc.

If you're running a recent-ish UNIX-derivative, it's probably best to just download packeteer and try to compile it.

Instructions

  1. pip install meson
  2. mkdir build && cd build
  3. meson ..
  4. ninja

Instructions (Android)

  1. pip install meson pipenv
  2. pipenv install
  3. pipenv run ./android.py
  4. mkdir build && cd build
  5. meson --cross-file ../android-<target>.txt ..
  6. ninja

Replace <target> with the specific Android target you wish to build for.

Scope

Design Goals

  1. Cross platform (highest priority)
  2. Low usage complexity
  3. Stable API/ABI
  4. Packet oriented I/O friendly
  5. Scalable
  6. Efficient
  7. Extensible (lowest priority)

The ordering of the goals is somewhat important. If you're just looking for fast event notification, there are better projects out there. If you're just looking for TCP streams, there are better projects, etc.

The overarching goal is to have very little effort in developing client and server implementations for new low-level protocols.

Supported Connectors

  • TCP/IP via the "tcp", "tcp4" and "tcp6" schemes.
  • UDP/IP via the "udp", "udp4" and "udp6" schemes.
  • AF_LOCAL/AF_UNIX via the "local" scheme. Note that unnamed local sockets are emulated on Windows, and abstract local names are not supported on all platforms.
  • Windows named pipes via the "pipe" scheme.
  • POSIX named pipes via the "fifo" scheme.
  • The "anon" scheme maps to POSIX anonymous pipes, or Windows named pipes with a generated name, and is usable for IPC within a process.

License

See the COPYING file.