inbox.hpp

Go to the documentation of this file.

/*
 
Copyright 2025 Matthew Tolman
 
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
 
   http://www.apache.org/licenses/LICENSE-2.0
 
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
 
*/
 
#ifndef MTCORE_MTTHREAD_INBOX_HPP
#define MTCORE_MTTHREAD_INBOX_HPP
 
#include "mtcore/colls/queue.hpp"
#include "mtcore_thread/channels.hpp"
#include "mtcore_thread/core.hpp"
#include <mutex>
 
namespace mtcore::thread {
  enum class ChannelGrowTrySendErrors {
    CHANNEL_CLOSED,
    COULD_NOT_LOCK,
    NO_ROOM,
    ALLOCATION_FAILED,
  };

  enum class ChannelGrowSendBlockErrors {
    CHANNEL_CLOSED,
    ALLOCATION_FAILED,
  };

  enum class ChannelGrowSendBeforeErrors {
    CHANNEL_CLOSED,
    TIMEOUT,
    ALLOCATION_FAILED,
  };

  template<typename T>
  struct Inbox {
  private:
    Queue<T> q;
    std::timed_mutex channelMux           = {};
    std::condition_variable_any read_cond = {};
    std::condition_variable_any send_cond = {};
    bool closed                           = false;
 
  public:
    using Message = T;

    Result<void, AllocationError> init(Allocator &alloc, size_t initCapacity = 10) {
      auto lock = std::unique_lock(channelMux);
      ensure(!initialized(), "Already initialized! memory leak detected!");
      return q.init(alloc, initCapacity);
    }

    void deinit(Allocator &alloc) {
      auto lock = std::unique_lock(channelMux);
      q.deinit(alloc);
      ensure(!initialized(), "CLEAN UP FAILED!");
    }

    void close() {
      auto lock = std::unique_lock(channelMux);
      ensure(initialized(), "NOT INITIALIZED!");
      closed = true;
      send_cond.notify_all();
      read_cond.notify_all();
    }

    [[nodiscard]] Result<void, ChannelTrySendErrors> try_send(const T &msg) {
      auto lock = std::unique_lock(channelMux, std::try_to_lock_t{});
      ensure(initialized(), "NOT INITIALIZED!");
 
      if (!lock.owns_lock()) {
        return error(ChannelTrySendErrors::CHANNEL_CLOSED);
      }
 
      if (closed) {
        return error(ChannelTrySendErrors::CHANNEL_CLOSED);
      }
 
      if (q.is_full()) {
        return error(ChannelTrySendErrors::NO_ROOM);
      }
 
      (void) q.push(msg);
      read_cond.notify_one();
      return success();
    }

    [[nodiscard]] Result<void, ChannelSendBlockErrors> send_block(const T &msg) {
      auto lock = std::unique_lock(channelMux);
      ensure(lock.owns_lock(), "DID NOT LOCK");
      ensure(initialized(), "NOT INITIALIZED!");
 
      while (!closed && q.is_full()) {
        send_cond.wait(lock);
      }
      if (closed) {
        return error(ChannelSendBlockErrors::CHANNEL_CLOSED);
      }
 
      (void) q.push(msg);
      read_cond.notify_one();
      return success();
    }

    template<typename Clock = std::chrono::steady_clock, typename Duration>
    [[nodiscard]] Result<void, ChannelSendBeforeErrors>
    send_before(const T &msg, const std::chrono::time_point<Clock, Duration> &when) {
      auto lock = std::unique_lock(channelMux, when);
      if (!lock.owns_lock()) {
        return error(ChannelSendBeforeErrors::TIMEOUT);
      }
      ensure(initialized(), "NOT INITIALIZED!");
 
      while (!closed && q.is_full()) {
        if (send_cond.wait_until(lock, when) == std::cv_status::timeout) {
          return error(ChannelSendBeforeErrors::TIMEOUT);
        }
      }
      if (closed) {
        return error(ChannelSendBeforeErrors::CHANNEL_CLOSED);
      }
 
      (void) q.push(msg);
      read_cond.notify_one();
      return success();
    }

    [[nodiscard]] Result<void, ChannelGrowTrySendErrors> try_send(Allocator &alloc, const T &msg) {
      auto lock = std::unique_lock(channelMux, std::try_to_lock_t{});
 
      if (!lock.owns_lock()) {
        return error(ChannelGrowTrySendErrors::COULD_NOT_LOCK);
      }
      ensure(initialized(), "NOT INITIALIZED!");
 
      if (closed) {
        return error(ChannelGrowTrySendErrors::CHANNEL_CLOSED);
      }
 
      bool emit_notice = q.is_full();
      auto res         = q.push(alloc, msg);
      if (res.is_error()) {
        return error(ChannelGrowTrySendErrors::ALLOCATION_FAILED);
      }
      read_cond.notify_one();
 
      // tell everyone else our capacity has grown
      if (emit_notice) {
        send_cond.notify_all();
      }
      return success();
    }

    [[nodiscard]] Result<void, ChannelGrowSendBlockErrors> send_block(Allocator &alloc, const T &msg) {
      auto lock = std::unique_lock(channelMux);
      ensure(lock.owns_lock(), "DID NOT LOCK");
      ensure(initialized(), "NOT INITIALIZED!");
 
      while (!closed && q.is_full()) {
        send_cond.wait(lock);
      }
      if (closed) {
        return error(ChannelGrowSendBlockErrors::CHANNEL_CLOSED);
      }
 
      bool emit_notice = q.is_full();
      auto res         = q.push(alloc, msg);
      if (res.is_error()) {
        // If we couldn't resize, just wait for room
        emit_notice = false;
        while (!is_closed() && q.is_full()) {
          send_cond.wait(lock);
        }
 
        // check if we closed
        if (is_closed()) {
          return error(ChannelGrowSendBlockErrors::CHANNEL_CLOSED);
        }
 
        // try sending again
        if (auto err = q.push(msg); err.is_error()) {
          return error(ChannelGrowSendBlockErrors::ALLOCATION_FAILED);
        }
      }
      read_cond.notify_one();
 
      // tell everyone else our capacity has grown
      if (emit_notice) {
        send_cond.notify_all();
      }
      return success();
    }

    template<typename Clock = std::chrono::steady_clock, typename Duration>
    [[nodiscard]] Result<void, ChannelGrowSendBeforeErrors>
    send_before(Allocator &alloc, const T &msg, const std::chrono::time_point<Clock, Duration> &when) {
      auto lock = std::unique_lock(channelMux, when);
      if (!lock.owns_lock()) {
        return error(ChannelGrowSendBeforeErrors::TIMEOUT);
      }
      ensure(initialized(), "NOT INITIALIZED!");
 
      if (is_closed()) {
        return error(ChannelGrowSendBeforeErrors::CHANNEL_CLOSED);
      }
 
      bool emit_notice = q.is_full();
 
      auto res = q.push(alloc, msg);
      if (res.is_error()) {
        ensure(res.error().code == AllocationError::ALLOCATION_FAILED);
        // If we couldn't resize, just wait for room
        emit_notice = false;
        while (!is_closed() && q.is_full()) {
          if (send_cond.wait_until(lock, when) == std::cv_status::timeout) {
            return error(ChannelGrowSendBeforeErrors::TIMEOUT);
          }
        }
 
        // check if we closed
        if (is_closed()) {
          return error(ChannelGrowSendBeforeErrors::CHANNEL_CLOSED);
        }
 
        // try sending again
        if (auto err = q.push(msg); err.is_error()) {
          return error(ChannelGrowSendBeforeErrors::ALLOCATION_FAILED);
        }
      }
      read_cond.notify_one();
 
      // tell everyone else our capacity has grown
      if (emit_notice) {
        send_cond.notify_all();
      }
      return success();
    }

    [[nodiscard]] Result<Optional<T>, ChannelTryReceiveErrors> try_receive() {
      auto lock = std::unique_lock(channelMux, std::try_to_lock_t{});
 
      if (!lock.owns_lock()) {
        return error(ChannelTryReceiveErrors::COULD_NOT_LOCK);
      }
      ensure(initialized(), "NOT INITIALIZED!");
 
      if (q.is_empty()) {
        if (closed) {
          return readImpl();
        }
        return error(ChannelTryReceiveErrors::MESSAGE_NOT_READY);
      }
 
      ensure(lock.owns_lock(), "DID NOT LOCK!");
      return readImpl();
    }

    [[nodiscard]] Optional<T> receive_block() {
      auto lock = std::unique_lock(channelMux);
      ensure(initialized(), "NOT INITIALIZED!");
 
      while (!closed && q.is_empty()) {
        read_cond.wait(lock);
      }
 
      ensure(lock.owns_lock(), "DID NOT LOCK");
      return readImpl();
    }

    template<typename Clock, typename Duration>
    [[nodiscard]] Result<Optional<T>, ChannelSendBeforeErrors>
    receive_before(const std::chrono::time_point<Clock, Duration> &when) {
      auto lock = std::unique_lock(channelMux, when);
 
      if (!lock.owns_lock()) {
        return error(ChannelSendBeforeErrors::TIMEOUT);
      }
      ensure(initialized(), "NOT INITIALIZED!");
 
      while (!closed && q.is_empty()) {
        if (read_cond.wait_until(lock, when) == std::cv_status::timeout) {
          return error(ChannelSendBeforeErrors::TIMEOUT);
        }
      }
 
      ensure(lock.owns_lock(), "DID NOT LOCK");
      return readImpl();
    }

    [[nodiscard]] bool is_initialized() const noexcept {
      auto lock = std::unique_lock(channelMux);
      return initialized();
    }

    void shrinkToFit(Allocator &alloc) {
      auto lock = std::unique_lock(channelMux);
      ensure(lock.owns_lock(), "DID NOT LOCK");
      ensure(initialized(), "NOT INITIALIZED!");
 
      q.shrink_to_fit(alloc);
    }
 
  private:
    Optional<T> readImpl() {
      if (closed && q.is_empty()) {
        return nullopt;
      }
      ensure(!q.is_empty(), "CANNOT READ FROM EMPTY BUFFER");
      send_cond.notify_one();
      return q.pop();
    }
 
    [[nodiscard]] bool initialized() const noexcept { return q.is_initialized(); }
 
    [[nodiscard]] bool is_closed() const noexcept { return closed; }
  };
  static_assert(is_channel_like_grow<Inbox<int>>, "Inbox<int> is not growing channel-like");
}  // namespace mtcore::thread
 
#endif  // MTCORE_MTTHREAD_INBOX_HPP