Develop

include/libipc/condition.h

@@ -27,8 +27,8 @@ class IPC_EXPORT condition {
     void close() noexcept;
 
     bool wait(ipc::sync::mutex &mtx, std::uint64_t tm = ipc::invalid_value) noexcept;
-    bool notify() noexcept;
-    bool broadcast() noexcept;
+    bool notify(ipc::sync::mutex &mtx) noexcept;
+    bool broadcast(ipc::sync::mutex &mtx) noexcept;
 
 private:
     class condition_;

src/CMakeLists.txt

@@ -1,12 +1,8 @@
 project(ipc)
 
-if(UNIX)
-  file(GLOB SRC_FILES ${LIBIPC_PROJECT_DIR}/src/libipc/platform/*_linux.cpp)
-else()
-  file(GLOB SRC_FILES ${LIBIPC_PROJECT_DIR}/src/libipc/platform/*_win.cpp)
-endif()
 aux_source_directory(${LIBIPC_PROJECT_DIR}/src/libipc SRC_FILES)
 aux_source_directory(${LIBIPC_PROJECT_DIR}/src/libipc/sync SRC_FILES)
+aux_source_directory(${LIBIPC_PROJECT_DIR}/src/libipc/platform SRC_FILES)
 
 file(GLOB HEAD_FILES
   ${LIBIPC_PROJECT_DIR}/include/libipc/*.h
@@ -33,28 +29,27 @@ set_target_properties(${PROJECT_NAME}
 	PROPERTIES
 	ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib"
 	LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib"
-	RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin" )
+	RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
 
 # set version
 set_target_properties(${PROJECT_NAME}
     PROPERTIES
-    VERSION 1.1.0
-    SOVERSION 2)
+    VERSION 1.2.0
+    SOVERSION 3)
 
 target_include_directories(${PROJECT_NAME}
   PUBLIC  ${LIBIPC_PROJECT_DIR}/include
   PRIVATE ${LIBIPC_PROJECT_DIR}/src
-)
+          $<$<BOOL:UNIX>:${LIBIPC_PROJECT_DIR}/src/libipc/platform/linux>)
 
 if(NOT MSVC)
   target_link_libraries(${PROJECT_NAME} PUBLIC
-    pthread
-    $<$<NOT:$<STREQUAL:${CMAKE_SYSTEM_NAME},Windows>>:rt>)
+    $<$<NOT:$<STREQUAL:${CMAKE_SYSTEM_NAME},QNX>>:pthread>
+    $<$<NOT:$<OR:$<STREQUAL:${CMAKE_SYSTEM_NAME},Windows>,$<STREQUAL:${CMAKE_SYSTEM_NAME},QNX>>>:rt>)
 endif()
 
 install(
   TARGETS ${PROJECT_NAME}
   RUNTIME DESTINATION bin
   LIBRARY DESTINATION lib
-  ARCHIVE DESTINATION lib
-)
+  ARCHIVE DESTINATION lib)

src/libipc/ipc.cpp

@@ -687,8 +687,8 @@ buff_t chan_impl<Flag>::try_recv(ipc::handle_t h) {
 }
 
 template struct chan_impl<ipc::wr<relat::single, relat::single, trans::unicast  >>;
-template struct chan_impl<ipc::wr<relat::single, relat::multi , trans::unicast  >>;
-template struct chan_impl<ipc::wr<relat::multi , relat::multi , trans::unicast  >>;
+// template struct chan_impl<ipc::wr<relat::single, relat::multi , trans::unicast  >>; // TBD
+// template struct chan_impl<ipc::wr<relat::multi , relat::multi , trans::unicast  >>; // TBD
 template struct chan_impl<ipc::wr<relat::single, relat::multi , trans::broadcast>>;
 template struct chan_impl<ipc::wr<relat::multi , relat::multi , trans::broadcast>>;
 

src/libipc/platform/detail.h

@@ -1,4 +1,22 @@
-#pragma once
+#ifndef LIBIPC_SRC_PLATFORM_DETAIL_H_
+#define LIBIPC_SRC_PLATFORM_DETAIL_H_
+
+// detect platform
+
+#if defined(WIN64) || defined(_WIN64) || defined(__WIN64__) || \
+    defined(WIN32) || defined(_WIN32) || defined(__WIN32__) || defined(__NT__) || \
+    defined(WINCE) || defined(_WIN32_WCE)
+#   define IPC_OS_WINDOWS_
+#elif defined(__linux__) || defined(__linux)
+#   define IPC_OS_LINUX_
+#elif defined(__QNX__)
+#   define IPC_OS_QNX_
+#elif defined(__APPLE__)
+#elif defined(__ANDROID__)
+// TBD
+#endif
+
+#if defined(__cplusplus)
 
 #include <memory>
 #include <mutex>
@@ -22,18 +40,6 @@
 #   error "IPC_CONSTEXPR_ has been defined."
 #endif
 
-// detect platform
-
-#if defined(WIN64) || defined(_WIN64) || defined(__WIN64__) || \
-    defined(WIN32) || defined(_WIN32) || defined(__WIN32__) || defined(__NT__) || \
-    defined(WINCE) || defined(_WIN32_WCE)
-#   define IPC_OS_WINDOWS_
-#endif/*WIN*/
-
-#if defined(__linux__) || defined(__linux)
-#   define IPC_OS_LINUX_
-#endif/*linux*/
-
 #if __cplusplus >= 201703L
 
 #define IPC_UNUSED_      [[maybe_unused]]
@@ -123,17 +129,8 @@ constexpr const T& (min)(const T& a, const T& b) {
 
 #endif/*__cplusplus < 201703L*/
 
-template <typename T, typename U>
-auto horrible_cast(U rhs) noexcept
-    -> typename std::enable_if<std::is_trivially_copyable<T>::value
-                            && std::is_trivially_copyable<U>::value, T>::type {
-    union {
-        T t;
-        U u;
-    } r = {};
-    r.u = rhs;
-    return r.t;
-}
-
 } // namespace detail
 } // namespace ipc
+
+#endif // defined(__cplusplus)
+#endif // LIBIPC_SRC_PLATFORM_DETAIL_H_

src/libipc/platform/linux/a0/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org>

src/libipc/platform/linux/a0/README.md

@@ -0,0 +1,213 @@
+<h1 align="center">
+  <br>
+  <img src="https://raw.githubusercontent.com/alephzero/logo/master/rendered/alephzero.svg" width="256px">
+  <br>
+  AlephZero
+</h1>
+
+<h3 align="center">Simple, Robust, Fast IPC.</h3>
+
+<p align="center">
+  <a href="https://github.com/alephzero/alephzero/actions?query=workflow%3ACI"><img src="https://github.com/alephzero/alephzero/workflows/CI/badge.svg"></a>
+  <a href="https://codecov.io/gh/alephzero/alephzero"><img src="https://codecov.io/gh/alephzero/alephzero/branch/master/graph/badge.svg"></a>
+  <a href="https://alephzero.readthedocs.io/en/latest/?badge=latest"><img src="https://readthedocs.org/projects/alephzero/badge/?version=latest"></a>
+  <a href="http://unlicense.org"><img src="https://img.shields.io/badge/license-Unlicense-blue.svg"></a>
+</p>
+
+<p align="center">
+  <a href="#overview">Overview</a> •
+  <a href="#transport">Transport</a> •
+  <a href="#protocol">Protocol</a> •
+  <a href="#examples">Examples</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#across-dockers">Across Dockers</a>
+</p>
+
+# Overview
+
+[Presentation from March 25, 2020](https://docs.google.com/presentation/d/12KE9UucjZPtpVnM1NljxOqBolBBKECWJdrCoE2yJaBw/edit#slide=id.p)
+
+AlephZero is a library for message based communication between programs running on the same machine.
+
+## Simple
+
+AlephZero's main goal is to be simple to use. Nothing is higher priority.
+
+There is no "master" process in between your nodes that is needed to do handshakes or exchanges of any kind. All you need is the topic name.
+
+See the <a href="#examples">Examples</a>.
+
+## Robust
+
+This is probably the main value of AlephZero, above similar libraries.
+
+AlephZero uses a lot of tricks to ensure the state of all channels is consistent, even when programs die. This includes double-buffering the state of the communication channel and [robustifying](https://man7.org/linux/man-pages/man3/pthread_mutexattr_setrobust.3.html) the locks and notification channels.
+
+## Fast
+
+AlephZero uses shared memory across multiple processes to read and write messages, minimizing the involvement of the kernel. The kernel only really gets involved in notifying a process that a new message exists, and for that we use futex (fast user-space mutex).
+
+TODO: Benchmarks
+
+# Transport
+
+AlephZero, at its core, is a simple allocator on top of a contiguous region of memory. Usually, shared-memory. The allocator of choice is a circular-linked-list, which is fast, simple, and sufficient for the protocol listed below. It also plays well with the robustness requirement.
+
+This has a number of implications. For one, this means that old messages are kept around until the space is needed. The oldest messages are always discarded before any more recent messages.
+
+# Protocol
+
+Rather than exposing the low-level transport directly, AlephZero provides a few higher level protocol:
+
+* <b>PubSub</b>: Broadcast published messages. Subscribers get notified.
+* <b>RPC</b>: Request-response.
+* <b>PRPC (Progressive RPC)</b>: Request-streaming response.
+* <b>Sessions</b>: Bi-directional channel of communication. Not yet implemented. Let me know if you want this.
+
+# Examples
+
+Many more example and an interactive experience can be found at: https://github.com/alephzero/playground
+
+For the curious, here are some simple snippets to get you started:
+
+To begin with, we need to include AlephZero:
+```cc
+#include <a0.h>
+```
+
+## PubSub
+
+You can have as many publisher and subscribers on the same topic as you wish. They just need to agree on the filename.
+
+```cc
+a0::Publisher p("my_pubsub_topic");
+p.pub("foo");
+```
+
+You just published `"foo"` to the `"my_pubsub_topic"`.
+
+To read those message, you can create a subscriber on the same topic:
+```cc
+a0::Subscriber sub(
+    "my_pubsub_topic",
+    A0_INIT_AWAIT_NEW,  // or MOST_RECENT or OLDEST
+    A0_ITER_NEWEST,     // or NEXT
+    [](a0::PacketView pkt_view) {
+      std::cout << "Got: " << pkt_view.payload() << std::endl;
+    });
+```
+The callback will trigger whenever a message is published.
+
+The `Subscriber` object spawns a thread that will read the topic and call the callback.
+
+The `A0_INIT` tells the subscriber where to start reading. 
+* `A0_INIT_AWAIT_NEW`: Start with messages published after the creation of the subscriber.
+* `A0_INIT_MOST_RECENT`: Start with the most recently published message. Useful for state and configuration. But be careful, this can be quite old!
+* `A0_INIT_OLDEST`: Topics keep a history of 16MB (unless configures otherwise). Start with the oldest thing still in there.
+
+The `A0_ITER` tells the subscriber how to continue reading messages. After each callback:
+* `A0_ITER_NEXT`: grab the sequentially next message. When you don't want to miss a thing.
+* `A0_ITER_NEWEST`: grab the newest available unread message. When you want to keep up with the firehose.
+
+```cc
+a0::SubscriberSync sub_sync(
+    "my_pubsub_topic",
+    A0_INIT_OLDEST, A0_ITER_NEXT);
+while (sub_sync.has_next()) {
+  auto pkt = sub_sync.next();
+  std::cout << "Got: " << pkt.payload() << std::endl;
+}
+```
+
+## RPC
+
+Create an `RpcServer`:
+
+```cc
+a0::RpcServer server(
+    "my_rpc_topic",
+    /* onrequest = */ [](a0::RpcRequest req) {
+        std::cout << "Got: " << req.pkt().payload() << std::endl;
+        req.reply("echo " + std::string(req.pkt().payload()));
+    },
+    /* oncancel = */ nullptr);
+```
+
+Create an `RpcClient`:
+
+```cc
+a0::RpcClient client("my_rpc_topic");
+client.send("client msg", [](a0::PacketView reply) {
+  std::cout << "Got: " << reply.payload() << std::endl;
+});
+```
+
+# Installation
+
+## Install From Source
+
+### Ubuntu Dependencies
+
+```sh
+apt install g++ make
+```
+
+### Alpine Dependencies
+
+```sh
+apk add g++ linux-headers make
+```
+
+### Download And Install
+
+```sh
+git clone https://github.com/alephzero/alephzero.git
+cd alephzero
+make install -j
+```
+
+## Install From Package
+
+Coming soon-ish. Let me know if you want this and I'll prioritize it. External support is much appreciated.
+
+## Integration
+
+### Command Line
+
+Add the following to g++ / clang commands.
+```sh
+-L${libdir} -lalephzero -lpthread
+```
+
+### Package-cfg
+
+```sh
+pkg-config --cflags --libs alephzero
+```
+
+### CMake
+
+Coming soon-ish. Let me know if you want this and I'll prioritize it. External support is much appreciated.
+
+### Bazel
+
+Coming soon-ish. Let me know if you want this and I'll prioritize it.
+
+# Across Dockers
+
+For programs running across different dockers to be able to communicate, we need to have them match up on two flags: `--ipc` and `--pid`.
+
+* `--ipc` shares the `/dev/shm` filesystem. This is necessary to open the same file topics.
+* `--pid` shares the process id namespace. This is necessary for the locking and notification systems.
+
+In the simplest case, you can set them both to `host` and talk through the system's global `/dev/shm` and process id namespace.
+```sh
+docker run --ipc=host --pid=host --name=foo foo_image
+docker run --ipc=host --pid=host --name=bar bar_image
+```
+
+Or, you can mark one as `shareable` and have the others connect to it:
+```sh
+docker run --ipc=shareable --pid=shareable --name=foo foo_image
+docker run --ipc=container:foo --pid=container:foo --name=bar bar_image
+```