zircon/system/ulib/dispatcher-pool/include/dispatcher-pool/dispatcher-channel.h

// Copyright 2017 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#pragma once

#include <zircon/compiler.h>
#include <zircon/types.h>
#include <lib/zx/channel.h>
#include <fbl/intrusive_double_list.h>
#include <fbl/intrusive_wavl_tree.h>
#include <fbl/mutex.h>
#include <fbl/ref_counted.h>
#include <fbl/ref_ptr.h>
#include <unistd.h>

#include <type_traits>

#include <dispatcher-pool/dispatcher-event-source.h>

namespace dispatcher {

// class Channel
//
// Channel is one of the EventSources in the dispatcher framework used to manage
// a zircon channel object.
//
// :: Handlers ::
//
// Two handlers are defined for channel event sources,
// one which becomes dispatched any time the channel has messages to read (the
// ProcessHandler), and one which becomes dispatched when a channel becomes
// closed (the ChannelClosedHandler).
//
// Returning an error from the process handler will cause the channel to
// automatically become deactivated.
//
// The ChannelClosedHandler is optional, but will be called from the execution
// domain context in the event that the peer's endpoint is closed, or if an
// error is returned during processing.  It will not be called if the user's own
// code explicitly deactivates the channel, either by deactivating the channel
// object itself, or by deactivating the execution domain that the channel is
// bound to.
//
// :: Activation ::
//
// Two forms of the Activate method are provided.  One requires that a valid
// zx::channel handle be supplied to the Channel object; this is the handle
// which will be monitored and dispatched by the Channel object.  The other form
// attempts to create a channel pair and use one half of the pair while
// returning the other half to the caller via an out-parameter, presumably so
// that they can hand this handle off to some other process which needs to
// communicate with the user.  A ProcessHandler must be provided during
// activation, a ChannelClosedHandler is optional.
//
// :: Reading/Writing ::
//
// Reading and writing on the channel is done using the Read and Write methods.
// Internally, the handle itself is protected with a lock making it safe to call
// Read or Write on a Channel object from any thread.  Attempts to read or write
// a channel which either has not been activated yet, or which has been
// deactivated, will fail.
//
// :: A Simple Example of Activation ::
//
// class Thingy : public fbl::RefCounted<Thingy> {
//   public:
//     zx_status_t ConnectToClient(zx::channel ch_handle);
//   ...
//   private:
//     fbl::RefPtr<dispatcher::ExecutionDomain> my_domain_;
//     zx_status_t ProcessClientMessage(Channel* ch) TA_REQ(my_domain_.token());
//     void ClientDisconnected(const Channel* ch) TA_REQ(my_domain_.token());
//   ...
// };
//
// zx_status_t Thingy::ConnectToClient(zx::channel ch_handle) {
//   fbl::RefPtr<Channel> ch = Channel::Create();
//   if (!ch) return ZX_ERR_NO_MEMORY;
//
//   Channel::ProcessHandler phandler(
//   [thingy = fbl::MakeRefPtr(this)](Channel* ch) {
//      OBTAIN_EXECUTION_DOMAIN_TOKEN(t, thingy->my_domain_->token());
//      return thingy->ProcessClientMessage(ch);
//   }
//
//   Channel::ChannelCloseHandler chandler(
//   [thingy = fbl::MakeRefPtr(this)](const Channel* ch) {
//      OBTAIN_EXECUTION_DOMAIN_TOKEN(t, thingy->my_domain_->token());
//      thingy->ClientDisconnected(ch);
//   }
//
//   return ch->Activate(std::move(ch_handle),
//                       my_domain_,
//                       std::move(phandler),
//                       std::move(dhandler));
// }
//
class Channel : public EventSource {
public:
    // Definitions of process and deactivation handlers.
    static constexpr size_t MAX_HANDLER_CAPTURE_SIZE = sizeof(void*) * 2;
    using ProcessHandler =
        fbl::InlineFunction<zx_status_t(Channel*), MAX_HANDLER_CAPTURE_SIZE>;
    using ChannelClosedHandler =
        fbl::InlineFunction<void(const Channel*), MAX_HANDLER_CAPTURE_SIZE>;

    // Create
    //
    // General method handles construction/initialization of a Channel subclass.
    // Given an implementation called 'MyChannel', invocation should look like:
    //
    //   auto my_channel = Channel::Create<MyChannel>(arg1, arg2, ...);
    //
    // Note: Implementers are encouraged to keep their constructor/destructor
    // protected/private. In order to do so, they should make sure to specify
    // 'friend class Channel' and 'friend class fbl::RefPtr<T>'.
    template <typename T = Channel, typename... ConstructorSignature>
    static fbl::RefPtr<T> Create(ConstructorSignature&&... args) {
        static_assert(std::is_base_of<Channel, T>::value, "Class must derive from Channel!");

        fbl::AllocChecker ac;
        auto ptr = fbl::AdoptRef(new (&ac) T(std::forward<ConstructorSignature>(args)...));

        if (!ac.check()) {
            return nullptr;
        }

        return ptr;
    }

    // Activate a channel, creating the channel pair and retuning the client's
    // channel endpoint in the process.
    //
    // This operation binds the Channel object to an ExecutionDomain, a
    // processing handler, and an optional deactivation handler.  The operation
    // will fail if the Channel has already been bound, or either the domain
    // reference or processing handler is invalid.
    zx_status_t Activate(zx::channel* client_channel_out,
                         fbl::RefPtr<ExecutionDomain> domain,
                         ProcessHandler process_handler,
                         ChannelClosedHandler channel_closed_handler = nullptr)
        __TA_EXCLUDES(obj_lock_);

    // Activate a channel, binding to the user supplied channel endpoint in the
    // process.
    zx_status_t Activate(zx::channel channel,
                         fbl::RefPtr<ExecutionDomain> domain,
                         ProcessHandler process_handler,
                         ChannelClosedHandler channel_closed_handler = nullptr)
        __TA_EXCLUDES(obj_lock_);

    void Deactivate() __TA_EXCLUDES(obj_lock_) override;

    zx_status_t Read(void* buf,
                     uint32_t buf_len,
                     uint32_t* bytes_read_out,
                     zx::handle* rxed_handle = nullptr)
        __TA_EXCLUDES(obj_lock_);

    zx_status_t Write(const void* buf,
                      uint32_t buf_len,
                      zx::handle&& tx_handle = zx::handle())
        __TA_EXCLUDES(obj_lock_);

protected:
    Channel() : EventSource(ZX_CHANNEL_READABLE | ZX_CHANNEL_PEER_CLOSED) { }
    friend class fbl::RefPtr<Channel>;

    void Dispatch(ExecutionDomain* domain) __TA_EXCLUDES(obj_lock_) override;

private:
    zx_status_t ActivateLocked(zx::channel channel, fbl::RefPtr<ExecutionDomain> domain)
        __TA_REQUIRES(obj_lock_);

    ProcessHandler       process_handler_;
    ChannelClosedHandler channel_closed_handler_;
};

}  // namespace dispatcher