llvm/lldb/include/lldb/Core/ThreadedCommunication.h

//===-- ThreadedCommunication.h ---------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//

#ifndef LLDB_CORE_THREADEDCOMMUNICATION_H
#define LLDB_CORE_THREADEDCOMMUNICATION_H

#include "lldb/Core/Communication.h"
#include "lldb/Host/HostThread.h"
#include "lldb/Utility/Broadcaster.h"

#include <atomic>
#include <mutex>
#include <string>

#include <cstddef>
#include <cstdint>

namespace lldb_private {

/// \class ThreadedCommunication ThreadedCommunication.h
/// "lldb/Core/ThreadedCommunication.h" Variation of Communication that
/// supports threaded reads.
///
/// ThreadedCommunication enhances the base Communication class with support
/// for multi-threaded mode.  In this mode, a read thread is spawned that
/// continually reads data and caches any received bytes. To start the read
/// thread clients call:
///
///     bool ThreadedCommunication::StartReadThread (Status *);
///
/// If true is returned a read thread has been spawned that will continually
/// execute a call to the pure virtual DoRead function:
///
///     size_t Communication::ReadFromConnection (void *, size_t, uint32_t);
///
/// When bytes are received the data gets cached in \a m_bytes and this class
/// will broadcast a \b eBroadcastBitReadThreadGotBytes event. Clients that
/// want packet based communication should override AppendBytesToCache. The
/// subclasses can choose to call the built in AppendBytesToCache with the \a
/// broadcast parameter set to false. This will cause the \b
/// eBroadcastBitReadThreadGotBytes event not get broadcast, and then the
/// subclass can post a \b eBroadcastBitPacketAvailable event when a full
/// packet of data has been received.
///
/// If the connection is disconnected a \b eBroadcastBitDisconnected event
/// gets broadcast. If the read thread exits a \b
/// eBroadcastBitReadThreadDidExit event will be broadcast. Clients can also
/// post a \b eBroadcastBitReadThreadShouldExit event to this object which
/// will cause the read thread to exit.
///
/// ThreadedCommunication inherits from Broadcaster which means it can be used
/// in conjunction with Listener to wait for multiple broadcaster objects and
/// multiple events from each of those objects. ThreadedCommunication defines a
/// set of pre-defined event bits (see enumerations definitions that start with
/// "eBroadcastBit" below).
class ThreadedCommunication : public Communication, public Broadcaster { … };

} // namespace lldb_private

#endif // LLDB_CORE_THREADEDCOMMUNICATION_H