UT_NetFDSet.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT_NetFDSet.h ( UT Library, C++)
 *
 * COMMENTS:
 */

#ifndef __UT_NetFDSet__
#define __UT_NetFDSet__

#include "UT_API.h"
#include "UT_Array.h"
#include "UT_NonCopyable.h"
#include "UT_SmallArray.h"
#include "UT_UniquePtr.h"

#include <SYS/SYS_Types.h>
#include <SYS/SYS_Compiler.h>

#include <stddef.h>

// ============================================================================
/// Types of IO events that UT_NetFDSet can monitor a file descriptor for.
enum class UT_NetFDEvent
{
    NETFD_READ = 0x1,
    NETFD_WRITE = 0x2,
    NETFD_ERROR = 0x4,
    NETFD_HANGUP = 0x8
};

// ============================================================================
// The different modes that UT_NetFDSet can monitor file descriptors in. The
// default mode is the easiest mode to run the monitor in and is the recommended
// mode to use for regular monitoring needs. In some cases its more performant
// to use NETFD_ET_MODE which isnt supported on all platforms (default back to
// the default mode if not support on the platform). The ET mode typically needs
// a lot of care to get correct otherwise the program could hault waiting
// forever. If using ET mode please take extreme care before using!!!
enum class UT_NetFDMode
{
    NETFD_DEFAULT_MODE = 0,
    NETFD_ET_MODE = 1
};

// ============================================================================
/// Abstracts the socket file descriptor set for select() or poll() calls.
class UT_API UT_NetFDSet
{
public:
    /// Constructor and desctructor.
    /// @param fast This informs the fd set to use the performant variant for
    ///             the platform. This is currently only support on some
    ///             platforms.
    /// @param mode The mode to run the fd set in.
    UT_NetFDSet(
            bool fast = false,
            UT_NetFDMode mode = UT_NetFDMode::NETFD_DEFAULT_MODE);
    ~UT_NetFDSet();

    UT_NON_COPYABLE(UT_NetFDSet)

    class UT_API EventInfo
    {
    public:
        EventInfo();

        uint8   myReadActivity:1, myWriteActivity: 1,
                myErrorActivity: 1, myHangupActivity: 1;
        int myFD;
    };

    /// Adds a file descriptor to the set with the intent of monitoring 
    /// the given IO event.
    bool add(int fd, UT_NetFDEvent event);
    /// Adds a file descriptor to the set with the intent of monitoring a set
    /// of given IO events.
    bool add(int fd, const UT_SmallArray<UT_NetFDEvent>& events);

    /// Modify a file descriptor flags.
    bool modify(int fd, const UT_SmallArray<UT_NetFDEvent>& events);

    /// Remove a file descriptor from the set.
    void                remove(int fd);

    /// Test whether a file descriptor is in the set
    bool                contains(int fd) const;

    /// Removes all added file descriptors for all events (resets the set).
    void                removeAll();

    /// Checks or waits for the IO events on the file descriptors in the set.
    /// Essentially it's a wrapper for select() or poll().
    /// @param timeout_ms The timeout to wait for connection (in miliseconds).
    ///         If zero, the call does not wait for the events, but instead
    ///         checks for the current state of the FDs in the set.
    ///         If negative, the call blocks indefinitely, waiting for the
    ///         first event. This is equivalent to passing NULL to select() or 
    ///         -1 to poll() as time value.
    /// 
    /// @return The total number of file descriptors on which there was
    ///         activitiy (events of the registered type), or -1 if error
    ///         occured. If time limit expires, returns 0.
    int                 checkEvents(int timeout_ms) const;

    /// Constants denoting special wait times for checkEvents()
    static const int INDEFINITE_WAIT;   // blocking indefinitely for events
    static const int NO_WAIT;           // returning immediately

    /// Returns true if the set contains no file descriptors.
    bool                isEmpty() const;

    /// Returns true if there was any IO activity of the given type 
    /// on the given file descriptor.
    bool                isActive(int fd, UT_NetFDEvent event) const;

    /// Get all IO activity from an fd. Returns false if something has gone
    /// wrong.
    ///
    /// @param fd This is the file descriptor to get the io information for.
    /// @param info This is the information about a IO activity from the
    ///             file descriptor provided.
    bool                getInfoWithFD(int fd, EventInfo& info) const;

    /// Get all events current events in the set. This will wait up to
    /// timeout_ms before returning.
    ///
    /// @param events   The list of all current events in the set. The size of
    ///         the array is 0..number of fd in set.
    /// @param timeout_ms       The maximum amount of time to wait before givin
    ///         up. The timeout is in ms.
    /// @return True if `events` has any events in the list.
    bool getAnyEvents(UT_Array<EventInfo>& events, int timeout_ms) const;

    /// In some cases the mode wont be decided until after the fd set is created.
    /// The mode CANNOT be changed while the fdset has fd in it!
    /// @param mode     The mode to run the fd set in.
    void setMode(UT_NetFDMode mode) { myMode = mode; }
    SYS_NO_DISCARD_RESULT UT_NetFDMode mode() const { return myMode; }
private:
    /// Used to tell what impl its using.
    bool myUsingFast;
    /// The mode to run the FD set in.
    UT_NetFDMode myMode;
    /// Delegate that implements actual IO check (eg, select() or poll()).
    static const size_t SIZEOF_IMPL = 1576;
    char                myImpl[SIZEOF_IMPL];
};


#endif