lldb/Core/Communication.h

//===-- Communication.h -----------------------------------------*- C++ -*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef liblldb_Communication_h_
#define liblldb_Communication_h_

// C Includes
// C++ Includes
#include <string>

// Other libraries and framework includes
// Project includes
#include "lldb/lldb-private.h"
#include "lldb/Core/Broadcaster.h"
#include "lldb/Core/Error.h"
#include "lldb/Host/Host.h"
#include "lldb/Host/Mutex.h"
#include "lldb/Host/Predicate.h"
#include "lldb/lldb-private.h"

namespace lldb_private {

//----------------------------------------------------------------------
/// @class Communication Communication.h "lldb/Core/Communication.h"
/// @brief An abstract communications class.
///
/// Communication is an class that handles data communication
/// between two data sources. It uses a Connection class to do the
/// real communication. This approach has a couple of advantages: it
/// allows a single instance of this class to be used even though its
/// connection can change. Connections could negotiate for different
/// connections based on abilities like starting with Bluetooth and
/// negotiating up to WiFi if available. It also allows this class to be
/// subclassed by any interfaces that don't want to give bytes but want
/// to validate and give out packets. This can be done by overriding:
///
/// AppendBytesToCache (const uint8_t *src, size_t src_len, bool broadcast);
///
/// Communication 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.
/// Communication defines a set of pre-defined event bits (see
/// enumerations definitions that start with "eBroadcastBit" below).
///
/// There are two modes in which communications can occur:
///     @li single-threaded
///     @li multi-threaded
///
/// In single-threaded mode, all reads and writes happen synchronously
/// on the calling thread.
///
/// In multi-threaded mode, a read thread is spawned that continually
/// reads data and caches any received bytes. To start the read thread
/// clients call:
///
///     bool Communication::StartReadThread (Error *);
///
/// If true is returned a read thead 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.
//----------------------------------------------------------------------
class Communication : public Broadcaster
{
public:
    enum {
        eBroadcastBitDisconnected           = (1 << 0), ///< Sent when the communications connection is lost.
        eBroadcastBitReadThreadGotBytes     = (1 << 1), ///< Sent by the read thread when bytes become available.
        eBroadcastBitReadThreadDidExit      = (1 << 2), ///< Sent by the read thread when it exits to inform clients.
        eBroadcastBitReadThreadShouldExit   = (1 << 3), ///< Sent by clients that need to cancel the read thread.
        eBroadcastBitPacketAvailable        = (1 << 4), ///< Sent when data received makes a complete packet.
        kLoUserBroadcastBit                 = (1 << 16),///< Subclasses can used bits 31:16 for any needed events.
        kHiUserBroadcastBit                 = (1 << 31),
        eAllEventBits                       = 0xffffffff
    };

    typedef void (*ReadThreadBytesReceived) (void *baton, const void *src, size_t src_len);


    //------------------------------------------------------------------
    /// Construct the Communication object with the specified name for
    /// the Broadcaster that this object inherits from.
    ///
    /// @param[in] broadcaster_name
    ///     The name of the broadcaster object.  This name should be as
    ///     complete as possible to uniquely identify this object. The
    ///     broadcaster name can be updated after the connect function
    ///     is called.
    //------------------------------------------------------------------
    Communication(const char * broadcaster_name);

    //------------------------------------------------------------------
    /// Destructor.
    ///
    /// The destructor is virtual since this class gets subclassed.
    //------------------------------------------------------------------
    virtual
    ~Communication();

    void
    Clear ();

    //------------------------------------------------------------------
    /// Poll for bytes available if the communications supports it.
    ///
    /// @param[in] timeout_usec
    ///     A timeout value in micro-seconds, UINT32_MAX for infinite
    ///     wait.
    ///
    /// @return
    ///     \b True if the bytes are, or became available within the
    ///     timeout period, \b false otherwise.
    //------------------------------------------------------------------
    virtual lldb::ConnectionStatus
    BytesAvailable (uint32_t timeout_usec, Error *error_ptr);

    //------------------------------------------------------------------
    /// Connect using the current connection by passing \a url to its
    /// connect function.
    /// string.
    ///
    /// @param[in] url
    ///     A string that contains all information needed by the
    ///     subclass to connect to another client.
    ///
    /// @return
    ///     \b True if the connect succeeded, \b false otherwise. The
    ///     internal error object should be filled in with an
    ///     appropriate value based on the result of this function.
    ///
    /// @see Error& Communication::GetError ();
    /// @see bool Connection::Connect (const char *url);
    //------------------------------------------------------------------
    lldb::ConnectionStatus
    Connect (const char *url, Error *error_ptr);

    //------------------------------------------------------------------
    /// Disconnect the communications connection if one is currently
    /// connected.
    ///
    /// @return
    ///     \b True if the disconnect succeeded, \b false otherwise. The
    ///     internal error object should be filled in with an
    ///     appropriate value based on the result of this function.
    ///
    /// @see Error& Communication::GetError ();
    /// @see bool Connection::Disconnect ();
    //------------------------------------------------------------------
    lldb::ConnectionStatus
    Disconnect (Error *error_ptr = NULL);

    //------------------------------------------------------------------
    /// Check if the connection is valid.
    ///
    /// @return
    ///     \b True if this object is currently connected, \b false
    ///     otherwise.
    //------------------------------------------------------------------
    bool
    IsConnected () const;

    bool
    HasConnection () const;
    //------------------------------------------------------------------
    /// Read bytes from the current connection.
    ///
    /// If no read thread is running, this function call the
    /// connection's Connection::BytesAvailable(uint32_t) method to
    /// wait for available data, and then call the
    /// Connection::Read(void *, size_t) function to get any available
    /// bytes if Connection::BytesAvailable(uint32_t) returned true.
    ///
    /// If a read thread has been started, this function will check for
    /// any cached bytes that have already been read and return any
    /// currently available bytes. If no bytes are cached, it will wait
    /// for the bytes to become available by listening for the \a
    /// eBroadcastBitReadThreadGotBytes event. If this function consumes
    /// all of the bytes in the cache, it will reset the
    /// \a eBroadcastBitReadThreadGotBytes event bit.
    ///
    /// @param[in] dst
    ///     A destination buffer that must be at least \a dst_len bytes
    ///     long.
    ///
    /// @param[in] dst_len
    ///     The number of bytes to attempt to read, and also the max
    ///     number of bytes that can be placed into \a dst.
    ///
    /// @param[in] timeout_usec
    ///     A timeout value in micro-seconds.
    ///
    /// @return
    ///     The number of bytes actually read.
    ///
    /// @see bool Connection::BytesAvailable (uint32_t);
    /// @see size_t Connection::Read (void *, size_t);
    //------------------------------------------------------------------
    size_t
    Read (void *dst,
          size_t dst_len,
          uint32_t timeout_usec,
          lldb::ConnectionStatus &status,
          Error *error_ptr);

    //------------------------------------------------------------------
    /// The actual write function that attempts to write to the
    /// communications protocol.
    ///
    /// Subclasses must override this function.
    ///
    /// @param[in] src
    ///     A source buffer that must be at least \a src_len bytes
    ///     long.
    ///
    /// @param[in] src_len
    ///     The number of bytes to attempt to write, and also the
    ///     number of bytes are currently available in \a src.
    ///
    /// @return
    ///     The number of bytes actually Written.
    //------------------------------------------------------------------
    size_t
    Write (const void *src,
           size_t src_len,
           lldb::ConnectionStatus &status,
           Error *error_ptr);

    //------------------------------------------------------------------
    /// Sets the connection that it to be used by this class.
    ///
    /// By making a communication class that uses different connections
    /// it allows a single communication interface to negotiate and
    /// change its connection without any interruption to the client.
    /// It also allows the Communication class to be subclassed for
    /// packet based communication.
    ///
    /// @param[in] connection
    ///     A connection that this class will own and destroy.
    ///
    /// @see
    ///     class Connection
    //------------------------------------------------------------------
    void
    SetConnection (Connection *connection);

    //------------------------------------------------------------------
    /// Starts a read thread whose sole purpose it to read bytes from
    /// the current connection. This function will call connection's
    /// read function:
    ///
    /// size_t Connection::Read (void *, size_t);
    ///
    /// When bytes are read and cached, this function will call:
    ///
    /// Communication::AppendBytesToCache (const uint8_t * bytes, size_t len, bool broadcast);
    ///
    /// Subclasses should override this function if they wish to override
    /// the default action of caching the bytes and broadcasting a \b
    /// eBroadcastBitReadThreadGotBytes event.
    ///
    /// @return
    ///     \b True if the read thread was successfully started, \b
    ///     false otherwise.
    ///
    /// @see size_t Connection::Read (void *, size_t);
    /// @see void Communication::AppendBytesToCache (const uint8_t * bytes, size_t len, bool broadcast);
    //------------------------------------------------------------------
    virtual bool
    StartReadThread (Error *error_ptr = NULL);

    //------------------------------------------------------------------
    /// Stops the read thread by cancelling it.
    ///
    /// @return
    ///     \b True if the read thread was successfully canceled, \b
    ///     false otherwise.
    //------------------------------------------------------------------
    virtual bool
    StopReadThread (Error *error_ptr = NULL);

    //------------------------------------------------------------------
    /// Checks if there is a currently running read thread.
    ///
    /// @return
    ///     \b True if the read thread is running, \b false otherwise.
    //------------------------------------------------------------------
    bool
    ReadThreadIsRunning ();

    //------------------------------------------------------------------
    /// The static read thread function. This function will call
    /// the "DoRead" function continuously and wait for data to become
    /// avaialble. When data is received it will append the available
    /// data to the internal cache and broadcast a
    /// \b eBroadcastBitReadThreadGotBytes event.
    ///
    /// @param[in] comm_ptr
    ///     A pointer to an instance of this class.
    ///
    /// @return
    ///     \b NULL.
    ///
    /// @see void Communication::ReadThreadGotBytes (const uint8_t *, size_t);
    //------------------------------------------------------------------
    static lldb::thread_result_t
    ReadThread (lldb::thread_arg_t comm_ptr);

    void
    SetReadThreadBytesReceivedCallback (ReadThreadBytesReceived callback,
                                        void *callback_baton);

    static const char *
    ConnectionStatusAsCString (lldb::ConnectionStatus status);

private:
    //------------------------------------------------------------------
    // For Communication only
    //------------------------------------------------------------------
    DISALLOW_COPY_AND_ASSIGN (Communication);

protected:
    std::auto_ptr<Connection> m_connection_ap; ///< The connection that is current in use by this communications class.
    lldb::thread_t m_read_thread; ///< The read thread handle in case we need to cancel the thread.
    bool m_read_thread_enabled;
    std::string m_bytes;    ///< A buffer to cache bytes read in the ReadThread function.
    Mutex m_bytes_mutex; ///< A mutex to protect multi-threaded access to the cached bytes.
    ReadThreadBytesReceived m_callback;
    void *m_callback_baton;

    size_t
    ReadFromConnection (void *dst,
                        size_t dst_len,
                        lldb::ConnectionStatus &status,
                        Error *error_ptr);
    //------------------------------------------------------------------
    /// Append new bytes that get read from the read thread into the
    /// internal object byte cache. This will cause a \b
    /// eBroadcastBitReadThreadGotBytes event to be broadcast if \a
    /// broadcast is true.
    ///
    /// Subclasses can override this function in order to inspect the
    /// received data and check if a packet is available.
    ///
    /// Subclasses can also still call this function from the
    /// overridden method to allow the caching to correctly happen and
    /// suppress the broadcasting of the \a eBroadcastBitReadThreadGotBytes
    /// event by setting \a broadcast to false.
    ///
    /// @param[in] src
    ///     A source buffer that must be at least \a src_len bytes
    ///     long.
    ///
    /// @param[in] src_len
    ///     The number of bytes to append to the cache.
    //------------------------------------------------------------------
    virtual void
    AppendBytesToCache (const uint8_t *src, size_t src_len, bool broadcast, lldb::ConnectionStatus status);

    //------------------------------------------------------------------
    /// Get any available bytes from our data cache. If this call
    /// empties the data cache, the \b eBroadcastBitReadThreadGotBytes event
    /// will be reset to signify no more bytes are available.
    ///
    /// @param[in] dst
    ///     A destination buffer that must be at least \a dst_len bytes
    ///     long.
    ///
    /// @param[in] dst_len
    ///     The number of bytes to attempt to read from the cache,
    ///     and also the max number of bytes that can be placed into
    ///     \a dst.
    ///
    /// @return
    ///     The number of bytes extracted from the data cache.
    //------------------------------------------------------------------
    size_t
    GetCachedBytes (void *dst, size_t dst_len);
};

} // namespace lldb_private

#endif  // liblldb_Communication_h_