ServerCore/EPoll.h

#ifndef __EPoll_h__
#define __EPoll_h__

#include "Log.h"
#include "Socket.h"
#include "Thread.h"
#include "TCPSession.h"
#include "Command.h"

namespace core {
   
   ///
   /// EPoll
   ///
   /// Manage socket events from the epoll system call.
   /// 
   /// Use this object to establish a socket server using the epoll network structure of Linux.
   ///
   /// Use this object to establish the basis of working with multiple sockets of all sorts
   /// using the epoll capabilities of the Linux platform.
   /// Socket objects can register with EPoll which will establish a communication mechanism
   /// with that socket. 
   /// 
   /// The maximum number of sockets to communicate with is specified on the
   /// start method. 
   ///
   /// Threads are used to establish a read queue for epoll. The desired number of threads (or
   /// queues) is established by a parameter on the start method.
   ///

   class EPoll : public Command {

    public:

      long long eventId = 0;

      ///
      /// The constructor for the BMAEPoll object.
      ///

      EPoll();

      ///
     /// The destructor for the BMAEPoll object.
      ///

      ~EPoll();

      ///
      /// Use the start() method to initiate the threads and begin epoll queue processing.
      ///
      /// @param numberOfThreads the number of threads to start for processing epoll entries.
      /// @param maxSockets the maximum number of open sockets that epoll will manage.
      /// @param scope optional - if given, its onThreadStart()/onThreadEnd() run once on
      ///   each worker thread, at the top/bottom of that thread's own lifetime. The SAME
      ///   scope instance is shared across every worker thread - see ThreadScope's own
      ///   doc comment. Not owned by EPoll; caller keeps it alive for the server's lifetime.
      ///

      bool start(int numberOfThreads, int maxSockets, ThreadScope *scope = NULL); ///< Start the BMAEPoll processing.
      
      ///
      /// Use the stop() method to initiate the shutdown process for the epoll socket management.
      /// 
      /// A complete shutdown of all managed sockets will be initiated by this method call. 
      ///
      
      bool stop(); ///< Stop and shut down the BMAEPoll processing.
      
      ///
      /// This method returns a true if the stop() method has been called and the epoll system 
      /// is shutting.
      ///
      
      bool isStopping(); ///< Returns a true if the stop command has been requested.

      ///
      /// Use this method to obtain the current descriptor socket number for the epoll function call.
      ///
      
      int getDescriptor(); ///< Return the descriptor for the ePoll socket.
      
      ///
      /// The maximum number of sockets that can be managed by the epoll system.
      ///
      
      int maxSockets; ///< The maximum number of socket allowed.
      
      ///
      /// Receive the epoll events and dispatch the event to the socket making the request.
      ///
      
      void eventReceived(struct epoll_event event); ///< Dispatch event to appropriate socket.
      
      ///
      /// The processCommand() method displays the thread array to the requesting console via the 
      /// session passed as parameter.
      ///
      /// @param session the session to write the requested data to. 
      ///

      int processCommand(coreutils::ZString &request, TCPSession &session) override; ///<Output the threads array to the console.

    private:

      int epfd;
      int numberOfThreads;
      std::vector<Thread> threads;
      volatile bool terminateThreads;
      // Guards ~EPoll()'s own call to stop() - false until start()
      // actually runs, so a never-started EPoll (numberOfThreads and
      // threads both still default/empty) doesn't have its destructor
      // iterate a garbage thread count. See ~EPoll()'s own doc comment
      // in EPoll.cpp for what this is actually protecting against.
      bool started;

   };

}

#endif