File indexing completed on 2024-04-28 04:01:23

 /* -*- C++ -*-
     This file declares the QueuePolicy class.
 
     SPDX-FileCopyrightText: 2004, 2005, 2006 Mirko Boehm <mirko@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 
     $Id: DebuggingAids.h 30 2005-08-16 16:16:04Z mirko $
 */
 
 #ifndef QUEUEPOLICY_H
 #define QUEUEPOLICY_H
 
 #include "jobpointer.h"
 #include "threadweaver_export.h"
 
 namespace ThreadWeaver
 {
 class JobInterface;
 
 /** @brief QueuePolicy is an interface for customizations of the queueing behaviour of jobs.
  *
  *  A job can have a number of queue policies assigned. In that case, the job is only
  *  executed when the method canRun() of all assigned policies return true. For every call to
  *  canRun() that returns true, it is guaranteed that the method free() or the method release()
  *  is called. Calling free() means the job has been executed, while calling release() means
  *  the job was not executed for external reasons, and will be tried later on.
  *
  *  As an example, dependencies can be implemented using a QueuePolicy: canRun() returns true
  *  when the job has no unresolved dependencies. free() and release() are empty.
  *
  *  A job can have multiple queue policies assigned, and will only be executed if all of them
  *  return true from canRun() within the same execution attempt. Jobs only keep a reference to the
  *  QueuePolicy. Therefore, the same policy object can be assigned to multiple jobs and this way
  *  control the way all those jobs are executed. Jobs never assume ownership of their assigned queue
  *  policies.
  */
 class THREADWEAVER_EXPORT QueuePolicy
 {
 public:
     virtual ~QueuePolicy()
     {
     }
 
     /** @brief canRun() is called before the job is executed.
      *  The job will only be executed if canRun() returns true.
      */
     virtual bool canRun(JobPointer) = 0;
 
     /** @brief free() is called after the job has been executed.
      *  It is guaranteed that free is called only after canRun()
      *  returned true at an earlier time.
      */
     virtual void free(JobPointer) = 0;
 
     /** @brief release() is called if canRun() returned true, but the job has not been executed for external reasons.
      *
      *  For example, a second QueuePolicy could have returned false from canRun() for the same job.
      */
     virtual void release(JobPointer) = 0;
 
     /** @brief destructing() is called when a Job that has this queue policy assigned gets destructed.
      */
     virtual void destructed(JobInterface *job) = 0;
 };
 
 }
 
 #endif