arangodb/Scheduler/Scheduler.h

////////////////////////////////////////////////////////////////////////////////
/// @brief input-output scheduler
///
/// @file
///
/// DISCLAIMER
///
/// Copyright 2010-2011 triagens GmbH, Cologne, Germany
///
/// Licensed under the Apache License, Version 2.0 (the "License");
/// you may not use this file except in compliance with the License.
/// You may obtain a copy of the License at
///
///     http://www.apache.org/licenses/LICENSE-2.0
///
/// Unless required by applicable law or agreed to in writing, software
/// distributed under the License is distributed on an "AS IS" BASIS,
/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
/// See the License for the specific language governing permissions and
/// limitations under the License.
///
/// Copyright holder is triAGENS GmbH, Cologne, Germany
///
/// @author Dr. Frank Celler
/// @author Achim Brandt
/// @author Copyright 2008-2011, triAGENS GmbH, Cologne, Germany
////////////////////////////////////////////////////////////////////////////////

#ifndef TRIAGENS_FYN_REST_SCHEDULER_H
#define TRIAGENS_FYN_REST_SCHEDULER_H 1

#include <Basics/Common.h>

////////////////////////////////////////////////////////////////////////////////
/// @defgroup Scheduler I/O Scheduler
////////////////////////////////////////////////////////////////////////////////

namespace triagens {
  namespace basics {
    class ConditionVariable;
  }

  namespace rest {
    class Task;

    ////////////////////////////////////////////////////////////////////////////////
    /// @brief event loop identifier
    ////////////////////////////////////////////////////////////////////////////////

    typedef uint32_t EventLoop;

    ////////////////////////////////////////////////////////////////////////////////
    /// @brief event handler identifier
    ////////////////////////////////////////////////////////////////////////////////

    typedef uint32_t EventToken;

    ////////////////////////////////////////////////////////////////////////////////
    /// @brief event type identifier
    ////////////////////////////////////////////////////////////////////////////////

    typedef uint32_t EventType;

    ////////////////////////////////////////////////////////////////////////////////
    /// @brief socket read event
    ////////////////////////////////////////////////////////////////////////////////

    uint32_t const EVENT_SOCKET_READ = 1;

    ////////////////////////////////////////////////////////////////////////////////
    /// @brief socket write event
    ////////////////////////////////////////////////////////////////////////////////

    uint32_t const EVENT_SOCKET_WRITE = 2;

    ////////////////////////////////////////////////////////////////////////////////
    /// @brief asynchronous event
    ////////////////////////////////////////////////////////////////////////////////

    uint32_t const EVENT_ASYNC = 4;

    ////////////////////////////////////////////////////////////////////////////////
    /// @brief timer event
    ////////////////////////////////////////////////////////////////////////////////

    uint32_t const EVENT_TIMER = 8;

    ////////////////////////////////////////////////////////////////////////////////
    /// @brief periodic event
    ////////////////////////////////////////////////////////////////////////////////

    uint32_t const EVENT_PERIODIC = 16;

    ////////////////////////////////////////////////////////////////////////////////
    /// @brief signal event
    ////////////////////////////////////////////////////////////////////////////////

    uint32_t const EVENT_SIGNAL = 32;

    ////////////////////////////////////////////////////////////////////////////////
    /// @brief automatically select an io backend
    ////////////////////////////////////////////////////////////////////////////////

    uint32_t const BACKEND_AUTO = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// @ingroup Scheduler
    /// @brief interface of a input-output scheduler
    ////////////////////////////////////////////////////////////////////////////////

    class Scheduler {
      private:
        Scheduler (Scheduler const&);
        Scheduler& operator= (Scheduler const&);

      public:

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief creates a single-threaded scheduler
        ////////////////////////////////////////////////////////////////////////////////

        static Scheduler* create ();

      public:

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief constructor
        ////////////////////////////////////////////////////////////////////////////////

        Scheduler () {
        }

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief destructor
        ////////////////////////////////////////////////////////////////////////////////

        virtual ~Scheduler () {
        }

      public:

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief checks if scheduler is shuting down
        ////////////////////////////////////////////////////////////////////////////////

        virtual bool isShutdownInProgress () = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief checks if scheduler is still running
        ////////////////////////////////////////////////////////////////////////////////

        virtual bool isRunning () = 0;

      public:

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief registers a new task
        ////////////////////////////////////////////////////////////////////////////////

        virtual void registerTask (Task*) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief unregisters a task
        ///
        /// Note that this method is called by the task itself when cleanupTask is
        /// executed. If a Task failed in setupTask, it must not call unregisterTask.
        ////////////////////////////////////////////////////////////////////////////////

        virtual void unregisterTask (Task*) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief destroys task
        ///
        /// Even if a Task failed in setupTask, it can still call destroyTask. The
        /// methods will delete the task.
        ////////////////////////////////////////////////////////////////////////////////

        virtual void destroyTask (Task*) = 0;

      public:

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief starts scheduler, keeps running
        ///
        /// The functions returns true, if the scheduler has been started. In this
        /// case the condition variable is signal as soon as at least one of the
        /// scheduler threads stops.
        ////////////////////////////////////////////////////////////////////////////////

        virtual bool start (basics::ConditionVariable*) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief starts shutdown sequence
        ////////////////////////////////////////////////////////////////////////////////

        virtual void beginShutdown () = 0;

      public:

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief called to display current status
        ////////////////////////////////////////////////////////////////////////////////

        virtual void reportStatus () = 0;

      public:

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief main event loop
        ////////////////////////////////////////////////////////////////////////////////

        virtual void eventLoop (EventLoop) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief wakes up an event loop
        ////////////////////////////////////////////////////////////////////////////////

        virtual void wakeupLoop (EventLoop) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief called to register a socket descriptor event
        ////////////////////////////////////////////////////////////////////////////////

        virtual EventToken installSocketEvent (EventLoop, EventType, Task*, socket_t) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief re-starts the socket events
        ////////////////////////////////////////////////////////////////////////////////

        virtual void startSocketEvents (EventToken) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief stops the socket events
        ////////////////////////////////////////////////////////////////////////////////

        virtual void stopSocketEvents (EventToken) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief called to register an asynchronous event
        ////////////////////////////////////////////////////////////////////////////////

        virtual EventToken installAsyncEvent (EventLoop, Task*) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief sends an asynchronous event
        ////////////////////////////////////////////////////////////////////////////////

        virtual void sendAsync (EventToken) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief called to register a timer event
        ////////////////////////////////////////////////////////////////////////////////

        virtual EventToken installTimerEvent (EventLoop, Task*, double timeout) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief clears a timer without removing it
        ////////////////////////////////////////////////////////////////////////////////

        virtual void clearTimer (EventToken) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief rearms a timer
        ////////////////////////////////////////////////////////////////////////////////

        virtual void rearmTimer (EventToken, double timeout) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief called to register a periodic event
        ////////////////////////////////////////////////////////////////////////////////

        virtual EventToken installPeriodicEvent (EventLoop, Task*, double offset, double intervall) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief rearms a periodic timer
        ////////////////////////////////////////////////////////////////////////////////

        virtual void rearmPeriodic (EventToken, double offset, double timeout) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief called to register a signal event
        ////////////////////////////////////////////////////////////////////////////////

        virtual EventToken installSignalEvent (EventLoop, Task*, int signal) = 0;

        ////////////////////////////////////////////////////////////////////////////////
        /// @brief called to unregister an event handler
        ////////////////////////////////////////////////////////////////////////////////

        virtual void uninstallEvent (EventToken) = 0;
    };
  }
}

#endif