lib/isc/task.c

	task.c revision 744304361cf3e76aba2409e011b772d7c4c47d11
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff/*
ca41b452ede6feaa9d8739ec3cae19389a7b0d03Bob Halley * Copyright (C) 1998-2001  Internet Software Consortium.
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff *
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * Permission to use, copy, modify, and distribute this software for any
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * purpose with or without fee is hereby granted, provided that the above
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * copyright notice and this permission notice appear in all copies.
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff *
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff */
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff/* $Id: task.c,v 1.82 2001/02/07 21:16:12 bwelling Exp $ */
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff/*
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * Principal Author: Bob Halley
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff */
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff/*
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff * XXXRTH  Need to document the states a task can be in, and the rules
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff * for changing states.
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff */
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff#include <config.h>
7df0472d8a76c83d2137bd9549414a30787d58cfBrian Wellington
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff#include <isc/condition.h>
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff#include <isc/event.h>
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff#include <isc/mem.h>
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff#include <isc/msgs.h>
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff#include <isc/platform.h>
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff#include <isc/string.h>
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff#include <isc/task.h>
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff#include <isc/thread.h>
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#include <isc/util.h>
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#ifndef ISC_PLATFORM_USETHREADS
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#include "task_p.h"
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#endif /* ISC_PLATFORM_USETHREADS */
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define ISC_TASK_NAMES 1
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#ifdef ISC_TASK_TRACE
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define XTRACE(m)       fprintf(stderr, "task %p thread %lu: %s\n", \
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff                       task, isc_thread_self(), (m))
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define XTTRACE(t, m)       fprintf(stderr, "task %p thread %lu: %s\n", \
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff                       (t), isc_thread_self(), (m))
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define XTHREADTRACE(m)     fprintf(stderr, "thread %lu: %s\n", \
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff                       isc_thread_self(), (m))
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#else
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define XTRACE(m)
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define XTTRACE(t, m)
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define XTHREADTRACE(m)
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#endif
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff/***
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff *** Types.
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff ***/
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Grafftypedef enum {
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    task_state_idle, task_state_ready, task_state_running,
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    task_state_done
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff} task_state_t;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define TASK_MAGIC          0x5441534BU /* TASK. */
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define VALID_TASK(t)           ((t) != NULL && \
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff                     (t)->magic == TASK_MAGIC)
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graffstruct isc_task {
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    /* Not locked. */
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    unsigned int            magic;
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff    isc_taskmgr_t *         manager;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    isc_mutex_t         lock;
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff    /* Locked by task lock. */
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff    task_state_t            state;
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff    unsigned int            references;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    isc_eventlist_t         events;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    isc_eventlist_t         on_shutdown;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    unsigned int            quantum;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    unsigned int            flags;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#ifdef ISC_TASK_NAMES
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    char                name[16];
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff    void *              tag;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#endif
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    /* Locked by task manager lock. */
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    LINK(isc_task_t)        link;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    LINK(isc_task_t)        ready_link;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff};
62e4837585f2d48ce9ef3ad6880d8fb75a578e58Andreas Gustafsson
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define TASK_F_SHUTTINGDOWN     0x01
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define TASK_SHUTTINGDOWN(t)        (((t)->flags & TASK_F_SHUTTINGDOWN) \
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff                     != 0)
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define TASK_MANAGER_MAGIC      0x54534B4DU /* TSKM. */
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#define VALID_MANAGER(m)        ((m) != NULL && \
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff                     (m)->magic == TASK_MANAGER_MAGIC)
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graffstruct isc_taskmgr {
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    /* Not locked. */
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    unsigned int            magic;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    isc_mem_t *         mctx;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    isc_mutex_t         lock;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    unsigned int            workers;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#ifdef ISC_PLATFORM_USETHREADS
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    isc_thread_t *          threads;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#endif /* ISC_PLATFORM_USETHREADS */
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    /* Locked by task manager lock. */
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    unsigned int            default_quantum;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    LIST(isc_task_t)        tasks;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    LIST(isc_task_t)        ready_tasks;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#ifdef ISC_PLATFORM_USETHREADS
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    isc_condition_t         work_available;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#endif /* ISC_PLATFORM_USETHREADS */
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    isc_boolean_t           exiting;
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff#ifndef ISC_PLATFORM_USETHREADS
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    unsigned int            refs;
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff#endif /* ISC_PLATFORM_USETHREADS */
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff};
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff#define DEFAULT_TASKMGR_QUANTUM     10
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff#define DEFAULT_DEFAULT_QUANTUM     5
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff#define FINISHED(m)         ((m)->exiting && EMPTY((m)->tasks))
62e4837585f2d48ce9ef3ad6880d8fb75a578e58Andreas Gustafsson
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff#ifndef ISC_PLATFORM_USETHREADS
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graffstatic isc_taskmgr_t *taskmgr = NULL;
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff#endif /* ISC_PLATFORM_USETHREADS */
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff/***
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff *** Tasks.
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff ***/
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graffstatic void
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Grafftask_finished(isc_task_t *task) {
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff    isc_taskmgr_t *manager = task->manager;
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff    REQUIRE(EMPTY(task->events));
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff    REQUIRE(EMPTY(task->on_shutdown));
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff    REQUIRE(task->references == 0);
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff    REQUIRE(task->state == task_state_done);
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff    XTRACE("task_finished");
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff    LOCK(&manager->lock);
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff    UNLINK(manager->tasks, task, link);
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff#ifdef ISC_PLATFORM_USETHREADS
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff    if (FINISHED(manager)) {
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff        /*
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff         * All tasks have completed and the
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff         * task manager is exiting.  Wake up
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff         * any idle worker threads so they
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff         * can exit.
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff         */
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff        BROADCAST(&manager->work_available);
1a0e33bc2044e1902493111db14cbf793083ac47Michael Graff    }
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff#endif /* ISC_PLATFORM_USETHREADS */
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff    UNLOCK(&manager->lock);
d736db6dc53e615e3f2d66d1ddbe28473694d107Michael Graff
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff    DESTROYLOCK(&task->lock);
291b0d910d115e41a4b69d0603c3376aebf0c630Michael Graff    task->magic = 0;
e24f605ad64182532640dc6721070456b13112d5Michael Graff    isc_mem_put(manager->mctx, task, sizeof *task);
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff}
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff
1a0e33bc2044e1902493111db14cbf793083ac47Michael Graffisc_result_t
291b0d910d115e41a4b69d0603c3376aebf0c630Michael Graffisc_task_create(isc_taskmgr_t *manager, unsigned int quantum,
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff        isc_task_t **taskp)
1a0e33bc2044e1902493111db14cbf793083ac47Michael Graff{
4e675038a097065ff13944232cd7c89ac5961984Michael Graff    isc_task_t *task;
4e675038a097065ff13944232cd7c89ac5961984Michael Graff    isc_boolean_t exiting;
4e675038a097065ff13944232cd7c89ac5961984Michael Graff
4e675038a097065ff13944232cd7c89ac5961984Michael Graff    REQUIRE(VALID_MANAGER(manager));
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff    REQUIRE(taskp != NULL && *taskp == NULL);
4e675038a097065ff13944232cd7c89ac5961984Michael Graff
291b0d910d115e41a4b69d0603c3376aebf0c630Michael Graff    task = isc_mem_get(manager->mctx, sizeof *task);
291b0d910d115e41a4b69d0603c3376aebf0c630Michael Graff    if (task == NULL)
291b0d910d115e41a4b69d0603c3376aebf0c630Michael Graff        return (ISC_R_NOMEMORY);
291b0d910d115e41a4b69d0603c3376aebf0c630Michael Graff    XTRACE("isc_task_create");
291b0d910d115e41a4b69d0603c3376aebf0c630Michael Graff    task->manager = manager;
291b0d910d115e41a4b69d0603c3376aebf0c630Michael Graff    if (isc_mutex_init(&task->lock) != ISC_R_SUCCESS) {
291b0d910d115e41a4b69d0603c3376aebf0c630Michael Graff        isc_mem_put(manager->mctx, task, sizeof *task);
d736db6dc53e615e3f2d66d1ddbe28473694d107Michael Graff        UNEXPECTED_ERROR(__FILE__, __LINE__,
291b0d910d115e41a4b69d0603c3376aebf0c630Michael Graff                 "isc_mutex_init() %s",
d736db6dc53e615e3f2d66d1ddbe28473694d107Michael Graff                 isc_msgcat_get(isc_msgcat, ISC_MSGSET_GENERAL,
d736db6dc53e615e3f2d66d1ddbe28473694d107Michael Graff                        ISC_MSG_FAILED, "failed"));
d736db6dc53e615e3f2d66d1ddbe28473694d107Michael Graff        return (ISC_R_UNEXPECTED);
d736db6dc53e615e3f2d66d1ddbe28473694d107Michael Graff    }
e24f605ad64182532640dc6721070456b13112d5Michael Graff    task->state = task_state_idle;
e24f605ad64182532640dc6721070456b13112d5Michael Graff    task->references = 1;
d736db6dc53e615e3f2d66d1ddbe28473694d107Michael Graff    INIT_LIST(task->events);
e24f605ad64182532640dc6721070456b13112d5Michael Graff    INIT_LIST(task->on_shutdown);
e24f605ad64182532640dc6721070456b13112d5Michael Graff    task->quantum = quantum;
d736db6dc53e615e3f2d66d1ddbe28473694d107Michael Graff    task->flags = 0;
d736db6dc53e615e3f2d66d1ddbe28473694d107Michael Graff#ifdef ISC_TASK_NAMES
291b0d910d115e41a4b69d0603c3376aebf0c630Michael Graff    memset(task->name, 0, sizeof task->name);
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff    task->tag = NULL;
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff#endif
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff    INIT_LINK(task, link);
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff    INIT_LINK(task, ready_link);
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff
e24f605ad64182532640dc6721070456b13112d5Michael Graff    exiting = ISC_FALSE;
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    LOCK(&manager->lock);
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    if (!manager->exiting) {
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff        if (task->quantum == 0)
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff            task->quantum = manager->default_quantum;
e24f605ad64182532640dc6721070456b13112d5Michael Graff        APPEND(manager->tasks, task, link);
e24f605ad64182532640dc6721070456b13112d5Michael Graff    } else
e24f605ad64182532640dc6721070456b13112d5Michael Graff        exiting = ISC_TRUE;
e24f605ad64182532640dc6721070456b13112d5Michael Graff    UNLOCK(&manager->lock);
e24f605ad64182532640dc6721070456b13112d5Michael Graff
e24f605ad64182532640dc6721070456b13112d5Michael Graff    if (exiting) {
e24f605ad64182532640dc6721070456b13112d5Michael Graff        DESTROYLOCK(&task->lock);
e24f605ad64182532640dc6721070456b13112d5Michael Graff        isc_mem_put(manager->mctx, task, sizeof *task);
e24f605ad64182532640dc6721070456b13112d5Michael Graff        return (ISC_R_SHUTTINGDOWN);
e24f605ad64182532640dc6721070456b13112d5Michael Graff    }
e24f605ad64182532640dc6721070456b13112d5Michael Graff
e24f605ad64182532640dc6721070456b13112d5Michael Graff    task->magic = TASK_MAGIC;
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    *taskp = task;
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff
e24f605ad64182532640dc6721070456b13112d5Michael Graff    return (ISC_R_SUCCESS);
1a0e33bc2044e1902493111db14cbf793083ac47Michael Graff}
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graffvoid
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graffisc_task_attach(isc_task_t *source, isc_task_t **targetp) {
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    /*
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff     * Attach *targetp to source.
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff     */
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    REQUIRE(VALID_TASK(source));
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    REQUIRE(targetp != NULL && *targetp == NULL);
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    XTTRACE(source, "isc_task_attach");
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    LOCK(&source->lock);
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    source->references++;
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    UNLOCK(&source->lock);
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    *targetp = source;
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff}
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graffstatic inline isc_boolean_t
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Grafftask_shutdown(isc_task_t *task) {
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    isc_boolean_t was_idle = ISC_FALSE;
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    isc_event_t *event, *prev;
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    /*
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff     * Caller must be holding the task's lock.
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff     */
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff    XTRACE("task_shutdown");
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff    if (! TASK_SHUTTINGDOWN(task)) {
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff        XTRACE(isc_msgcat_get(isc_msgcat, ISC_MSGSET_GENERAL,
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff                      ISC_MSG_SHUTTINGDOWN, "shutting down"));
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff        task->flags |= TASK_F_SHUTTINGDOWN;
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff        if (task->state == task_state_idle) {
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff            INSIST(EMPTY(task->events));
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff            task->state = task_state_ready;
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff            was_idle = ISC_TRUE;
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff        }
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff        INSIST(task->state == task_state_ready ||
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff               task->state == task_state_running);
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff        /*
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff         * Note that we post shutdown events LIFO.
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff         */
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff        for (event = TAIL(task->on_shutdown);
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff             event != NULL;
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff             event = prev) {
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff            prev = PREV(event, ev_link);
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff            DEQUEUE(task->on_shutdown, event, ev_link);
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff            ENQUEUE(task->events, event, ev_link);
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff        }
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff    }
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff    return (was_idle);
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff}
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graffstatic inline void
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Grafftask_ready(isc_task_t *task) {
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff    isc_taskmgr_t *manager = task->manager;
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff
7dbf5a0b64237aa3052f04f4c8f7d56be8ec5d79Michael Graff    REQUIRE(VALID_MANAGER(manager));
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff    REQUIRE(task->state == task_state_ready);
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff    XTRACE("task_ready");
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff    LOCK(&manager->lock);
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff    ENQUEUE(manager->ready_tasks, task, ready_link);
1a0e33bc2044e1902493111db14cbf793083ac47Michael Graff#ifdef ISC_PLATFORM_USETHREADS
e24f605ad64182532640dc6721070456b13112d5Michael Graff    SIGNAL(&manager->work_available);
4e675038a097065ff13944232cd7c89ac5961984Michael Graff#endif /* ISC_PLATFORM_USETHREADS */
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff    UNLOCK(&manager->lock);
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff}
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graffstatic inline isc_boolean_t
e24f605ad64182532640dc6721070456b13112d5Michael Grafftask_detach(isc_task_t *task) {
e24f605ad64182532640dc6721070456b13112d5Michael Graff
e24f605ad64182532640dc6721070456b13112d5Michael Graff    /*
c05e003dce672b2f8555a3e56857f29ce89c1677Michael Graff     * Caller must be holding the task lock.
2311073ce0ef26c0250e91e4a083d7cc94fa7d33Michael Graff     */
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff    REQUIRE(task->references > 0);
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    XTRACE("detach");
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff
74889a341cac183d477e15cfead391a8f7bdba95Michael Graff    task->references--;
ae7d0a4375abaecfd5c5b0816616d9882831e69bMichael Graff    if (task->references == 0 && task->state == task_state_idle) {
e4f074a2c2340ea80099beebecc3b89aa234fa8fMichael Graff        INSIST(EMPTY(task->events));
a3ab70dae26d009bf78b0594b2ab5eb9208f4b91Michael Graff        /*
         * There are no references to this task, and no
         * pending events.  We could try to optimize and
         * either initiate shutdown or clean up the task,
         * depending on its state, but it's easier to just
         * make the task ready and allow run() or the event
         * loop to deal with shutting down and termination.
         */
        task->state = task_state_ready;
        return (ISC_TRUE);
    }

    return (ISC_FALSE);
}

void
isc_task_detach(isc_task_t **taskp) {
    isc_task_t *task;
    isc_boolean_t was_idle;

    /*
     * Detach *taskp from its task.
     */

    REQUIRE(taskp != NULL);
    task = *taskp;
    REQUIRE(VALID_TASK(task));

    XTRACE("isc_task_detach");

    LOCK(&task->lock);
    was_idle = task_detach(task);
    UNLOCK(&task->lock);

    if (was_idle)
        task_ready(task);

    *taskp = NULL;
}

static inline isc_boolean_t
task_send(isc_task_t *task, isc_event_t **eventp) {
    isc_boolean_t was_idle = ISC_FALSE;
    isc_event_t *event;

    /*
     * Caller must be holding the task lock.
     */

    REQUIRE(eventp != NULL);
    event = *eventp;
    REQUIRE(event != NULL);
    REQUIRE(event->ev_type > 0);
    REQUIRE(task->state != task_state_done);

    XTRACE("task_send");

    if (task->state == task_state_idle) {
        was_idle = ISC_TRUE;
        INSIST(EMPTY(task->events));
        task->state = task_state_ready;
    }
    INSIST(task->state == task_state_ready ||
           task->state == task_state_running);
    ENQUEUE(task->events, event, ev_link);
    *eventp = NULL;

    return (was_idle);
}

void
isc_task_send(isc_task_t *task, isc_event_t **eventp) {
    isc_boolean_t was_idle;

    /*
     * Send '*event' to 'task'.
     */

    REQUIRE(VALID_TASK(task));

    XTRACE("isc_task_send");

    /*
     * We're trying hard to hold locks for as short a time as possible.
     * We're also trying to hold as few locks as possible.  This is why
     * some processing is deferred until after the lock is released.
     */
    LOCK(&task->lock);
    was_idle = task_send(task, eventp);
    UNLOCK(&task->lock);

    if (was_idle) {
        /*
         * We need to add this task to the ready queue.
         *
         * We've waited until now to do it because making a task
         * ready requires locking the manager.  If we tried to do
         * this while holding the task lock, we could deadlock.
         *
         * We've changed the state to ready, so no one else will
         * be trying to add this task to the ready queue.  The
         * only way to leave the ready state is by executing the
         * task.  It thus doesn't matter if events are added,
         * removed, or a shutdown is started in the interval
         * between the time we released the task lock, and the time
         * we add the task to the ready queue.
         */
        task_ready(task);
    }
}

void
isc_task_sendanddetach(isc_task_t **taskp, isc_event_t **eventp) {
    isc_boolean_t idle1, idle2;
    isc_task_t *task;

    /*
     * Send '*event' to '*taskp' and then detach '*taskp' from its
     * task.
     */

    REQUIRE(taskp != NULL);
    task = *taskp;
    REQUIRE(VALID_TASK(task));

    XTRACE("isc_task_sendanddetach");

    LOCK(&task->lock);
    idle1 = task_send(task, eventp);
    idle2 = task_detach(task);
    UNLOCK(&task->lock);

    /*
     * If idle1, then idle2 shouldn't be true as well since we're holding
     * the task lock, and thus the task cannot switch from ready back to
     * idle.
     */
    INSIST(!(idle1 && idle2));

    if (idle1 || idle2)
        task_ready(task);

    *taskp = NULL;
}

#define PURGE_OK(event) (((event)->ev_attributes & ISC_EVENTATTR_NOPURGE) == 0)

static unsigned int
dequeue_events(isc_task_t *task, void *sender, isc_eventtype_t first,
           isc_eventtype_t last, void *tag,
           isc_eventlist_t *events, isc_boolean_t purging)
{
    isc_event_t *event, *next_event;
    unsigned int count = 0;

    REQUIRE(VALID_TASK(task));
    REQUIRE(last >= first);

    XTRACE("dequeue_events");

    /*
     * Events matching 'sender', whose type is >= first and <= last, and
     * whose tag is 'tag' will be dequeued.  If 'purging', matching events
     * which are marked as unpurgable will not be dequeued.
     *
     * sender == NULL means "any sender", and tag == NULL means "any tag".
     */

    LOCK(&task->lock);

    for (event = HEAD(task->events); event != NULL; event = next_event) {
        next_event = NEXT(event, ev_link);
        if (event->ev_type >= first && event->ev_type <= last &&
            (sender == NULL || event->ev_sender == sender) &&
            (tag == NULL || event->ev_tag == tag) &&
            (!purging || PURGE_OK(event))) {
            DEQUEUE(task->events, event, ev_link);
            ENQUEUE(*events, event, ev_link);
            count++;
        }
    }

    UNLOCK(&task->lock);

    return (count);
}

unsigned int
isc_task_purgerange(isc_task_t *task, void *sender, isc_eventtype_t first,
            isc_eventtype_t last, void *tag)
{
    unsigned int count;
    isc_eventlist_t events;
    isc_event_t *event, *next_event;

    /*
     * Purge events from a task's event queue.
     */

    XTRACE("isc_task_purgerange");

    ISC_LIST_INIT(events);

    count = dequeue_events(task, sender, first, last, tag, &events,
                   ISC_TRUE);

    for (event = HEAD(events); event != NULL; event = next_event) {
        next_event = NEXT(event, ev_link);
        isc_event_free(&event);
    }

    /*
     * Note that purging never changes the state of the task.
     */

    return (count);
}

unsigned int
isc_task_purge(isc_task_t *task, void *sender, isc_eventtype_t type,
           void *tag)
{
    /*
     * Purge events from a task's event queue.
     */

    XTRACE("isc_task_purge");

    return (isc_task_purgerange(task, sender, type, type, tag));
}

isc_boolean_t
isc_task_purgeevent(isc_task_t *task, isc_event_t *event) {
    isc_event_t *curr_event, *next_event;

    /*
     * Purge 'event' from a task's event queue.
     *
     * XXXRTH:  WARNING:  This method may be removed before beta.
     */

    REQUIRE(VALID_TASK(task));

    /*
     * If 'event' is on the task's event queue, it will be purged,
     * unless it is marked as unpurgeable.  'event' does not have to be
     * on the task's event queue; in fact, it can even be an invalid
     * pointer.  Purging only occurs if the event is actually on the task's
     * event queue.
     *
     * Purging never changes the state of the task.
     */

    LOCK(&task->lock);
    for (curr_event = HEAD(task->events);
         curr_event != NULL;
         curr_event = next_event) {
        next_event = NEXT(curr_event, ev_link);
        if (curr_event == event && PURGE_OK(event)) {
            DEQUEUE(task->events, curr_event, ev_link);
            break;
        }
    }
    UNLOCK(&task->lock);

    if (curr_event == NULL)
        return (ISC_FALSE);

    isc_event_free(&curr_event);

    return (ISC_TRUE);
}

unsigned int
isc_task_unsendrange(isc_task_t *task, void *sender, isc_eventtype_t first,
             isc_eventtype_t last, void *tag,
             isc_eventlist_t *events)
{
    /*
     * Remove events from a task's event queue.
     */

    XTRACE("isc_task_unsendrange");

    return (dequeue_events(task, sender, first, last, tag, events,
                   ISC_FALSE));
}

unsigned int
isc_task_unsend(isc_task_t *task, void *sender, isc_eventtype_t type,
        void *tag, isc_eventlist_t *events)
{
    /*
     * Remove events from a task's event queue.
     */

    XTRACE("isc_task_unsend");

    return (dequeue_events(task, sender, type, type, tag, events,
                   ISC_FALSE));
}

isc_result_t
isc_task_onshutdown(isc_task_t *task, isc_taskaction_t action, const void *arg)
{
    isc_boolean_t disallowed = ISC_FALSE;
    isc_result_t result = ISC_R_SUCCESS;
    isc_event_t *event;

    /*
     * Send a shutdown event with action 'action' and argument 'arg' when
     * 'task' is shutdown.
     */

    REQUIRE(VALID_TASK(task));
    REQUIRE(action != NULL);

    event = isc_event_allocate(task->manager->mctx,
                   NULL,
                   ISC_TASKEVENT_SHUTDOWN,
                   action,
                   arg,
                   sizeof *event);
    if (event == NULL)
        return (ISC_R_NOMEMORY);

    LOCK(&task->lock);
    if (TASK_SHUTTINGDOWN(task)) {
        disallowed = ISC_TRUE;
        result = ISC_R_SHUTTINGDOWN;
    } else
        ENQUEUE(task->on_shutdown, event, ev_link);
    UNLOCK(&task->lock);

    if (disallowed)
        isc_mem_put(task->manager->mctx, event, sizeof *event);

    return (result);
}

void
isc_task_shutdown(isc_task_t *task) {
    isc_boolean_t was_idle;

    /*
     * Shutdown 'task'.
     */

    REQUIRE(VALID_TASK(task));

    LOCK(&task->lock);
    was_idle = task_shutdown(task);
    UNLOCK(&task->lock);

    if (was_idle)
        task_ready(task);
}

void
isc_task_destroy(isc_task_t **taskp) {

    /*
     * Destroy '*taskp'.
     */

    REQUIRE(taskp != NULL);

    isc_task_shutdown(*taskp);
    isc_task_detach(taskp);
}

void
isc_task_setname(isc_task_t *task, const char *name, void *tag) {

    /*
     * Name 'task'.
     */

    REQUIRE(VALID_TASK(task));

#ifdef ISC_TASK_NAMES
    LOCK(&task->lock);
    memset(task->name, 0, sizeof(task->name));
    strncpy(task->name, name, sizeof(task->name) - 1);
    task->tag = tag;
    UNLOCK(&task->lock);
#else
    (void)name;
    (void)tag;
#endif

}

const char *
isc_task_getname(isc_task_t *task) {
    return (task->name);
}

void *
isc_task_gettag(isc_task_t *task) {
    return (task->tag);
}


/***
 *** Task Manager.
 ***/
static void
dispatch(isc_taskmgr_t *manager) {
    isc_task_t *task;
#ifndef ISC_PLATFORM_USETHREADS
    unsigned int total_dispatch_count = 0;
#endif /* ISC_PLATFORM_USETHREADS */

    REQUIRE(VALID_MANAGER(manager));

    /*
     * Again we're trying to hold the lock for as short a time as possible
     * and to do as little locking and unlocking as possible.
     *
     * In both while loops, the appropriate lock must be held before the
     * while body starts.  Code which acquired the lock at the top of
     * the loop would be more readable, but would result in a lot of
     * extra locking.  Compare:
     *
     * Straightforward:
     *
     *  LOCK();
     *  ...
     *  UNLOCK();
     *  while (expression) {
     *      LOCK();
     *      ...
     *      UNLOCK();
     *
     *          Unlocked part here...
     *
     *      LOCK();
     *      ...
     *      UNLOCK();
     *  }
     *
     * Note how if the loop continues we unlock and then immediately lock.
     * For N iterations of the loop, this code does 2N+1 locks and 2N+1
     * unlocks.  Also note that the lock is not held when the while
     * condition is tested, which may or may not be important, depending
     * on the expression.
     *
     * As written:
     *
     *  LOCK();
     *  while (expression) {
     *      ...
     *      UNLOCK();
     *
     *          Unlocked part here...
     *
     *      LOCK();
     *      ...
     *  }
     *  UNLOCK();
     *
     * For N iterations of the loop, this code does N+1 locks and N+1
     * unlocks.  The while expression is always protected by the lock.
     */

    LOCK(&manager->lock);
    while (!FINISHED(manager)) {
#ifdef ISC_PLATFORM_USETHREADS
        /*
         * For reasons similar to those given in the comment in
         * isc_task_send() above, it is safe for us to dequeue
         * the task while only holding the manager lock, and then
         * change the task to running state while only holding the
         * task lock.
         */
        while (EMPTY(manager->ready_tasks) && !FINISHED(manager)) {
            XTHREADTRACE(isc_msgcat_get(isc_msgcat,
                            ISC_MSGSET_GENERAL,
                            ISC_MSG_WAIT, "wait"));
            WAIT(&manager->work_available, &manager->lock);
            XTHREADTRACE(isc_msgcat_get(isc_msgcat,
                            ISC_MSGSET_TASK,
                            ISC_MSG_AWAKE, "awake"));
        }
#else /* ISC_PLATFORM_USETHREADS */
        if (total_dispatch_count >= DEFAULT_TASKMGR_QUANTUM ||
            EMPTY(manager->ready_tasks))
            break;
#endif /* ISC_PLATFORM_USETHREADS */
        XTHREADTRACE(isc_msgcat_get(isc_msgcat, ISC_MSGSET_TASK,
                        ISC_MSG_WORKING, "working"));

        task = HEAD(manager->ready_tasks);
        if (task != NULL) {
            unsigned int dispatch_count = 0;
            isc_boolean_t done = ISC_FALSE;
            isc_boolean_t requeue = ISC_FALSE;
            isc_boolean_t finished = ISC_FALSE;
            isc_event_t *event;

            INSIST(VALID_TASK(task));

            /*
             * Note we only unlock the manager lock if we actually
             * have a task to do.  We must reacquire the manager
             * lock before exiting the 'if (task != NULL)' block.
             */
            DEQUEUE(manager->ready_tasks, task, ready_link);
            UNLOCK(&manager->lock);

            LOCK(&task->lock);
            INSIST(task->state == task_state_ready);
            task->state = task_state_running;
            XTRACE(isc_msgcat_get(isc_msgcat, ISC_MSGSET_GENERAL,
                          ISC_MSG_RUNNING, "running"));
            do {
                if (!EMPTY(task->events)) {
                    event = HEAD(task->events);
                    DEQUEUE(task->events, event, ev_link);

                    /*
                     * Execute the event action.
                     */
                    XTRACE(isc_msgcat_get(isc_msgcat,
                                ISC_MSGSET_TASK,
                                ISC_MSG_EXECUTE,
                                "execute action"));
                    if (event->ev_action != NULL) {
                        UNLOCK(&task->lock);
                        (event->ev_action)(task,event);
                        LOCK(&task->lock);
                    }
                    dispatch_count++;
#ifndef ISC_PLATFORM_USETHREADS
                    total_dispatch_count++;
#endif /* ISC_PLATFORM_USETHREADS */
                }

                if (task->references == 0 &&
                    EMPTY(task->events) &&
                    !TASK_SHUTTINGDOWN(task)) {
                    isc_boolean_t was_idle;

                    /*
                     * There are no references and no
                     * pending events for this task,
                     * which means it will not become
                     * runnable again via an external
                     * action (such as sending an event
                     * or detaching).
                     *
                     * We initiate shutdown to prevent
                     * it from becoming a zombie.
                     *
                     * We do this here instead of in
                     * the "if EMPTY(task->events)" block
                     * below because:
                     *
                     *  If we post no shutdown events,
                     *  we want the task to finish.
                     *
                     *  If we did post shutdown events,
                     *  will still want the task's
                     *  quantum to be applied.
                     */
                    was_idle = task_shutdown(task);
                    INSIST(!was_idle);
                }

                if (EMPTY(task->events)) {
                    /*
                     * Nothing else to do for this task
                     * right now.
                     */
                    XTRACE(isc_msgcat_get(isc_msgcat,
                                  ISC_MSGSET_TASK,
                                  ISC_MSG_EMPTY,
                                  "empty"));
                    if (task->references == 0 &&
                        TASK_SHUTTINGDOWN(task)) {
                        /*
                         * The task is done.
                         */
                        XTRACE(isc_msgcat_get(
                                   isc_msgcat,
                                   ISC_MSGSET_TASK,
                                   ISC_MSG_DONE,
                                   "done"));
                        finished = ISC_TRUE;
                        task->state = task_state_done;
                    } else
                        task->state = task_state_idle;
                    done = ISC_TRUE;
                } else if (dispatch_count >= task->quantum) {
                    /*
                     * Our quantum has expired, but
                     * there is more work to be done.
                     * We'll requeue it to the ready
                     * queue later.
                     *
                     * We don't check quantum until
                     * dispatching at least one event,
                     * so the minimum quantum is one.
                     */
                    XTRACE(isc_msgcat_get(isc_msgcat,
                                  ISC_MSGSET_TASK,
                                  ISC_MSG_QUANTUM,
                                  "quantum"));
                    task->state = task_state_ready;
                    requeue = ISC_TRUE;
                    done = ISC_TRUE;
                }
            } while (!done);
            UNLOCK(&task->lock);

            if (finished)
                task_finished(task);

            LOCK(&manager->lock);
            if (requeue) {
                /*
                 * We know we're awake, so we don't have
                 * to wakeup any sleeping threads if the
                 * ready queue is empty before we requeue.
                 *
                 * A possible optimization if the queue is
                 * empty is to 'goto' the 'if (task != NULL)'
                 * block, avoiding the ENQUEUE of the task
                 * and the subsequent immediate DEQUEUE
                 * (since it is the only executable task).
                 * We don't do this because then we'd be
                 * skipping the exit_requested check.  The
                 * cost of ENQUEUE is low anyway, especially
                 * when you consider that we'd have to do
                 * an extra EMPTY check to see if we could
                 * do the optimization.  If the ready queue
                 * were usually nonempty, the 'optimization'
                 * might even hurt rather than help.
                 */
                ENQUEUE(manager->ready_tasks, task,
                    ready_link);
            }
        }
    }
    UNLOCK(&manager->lock);
}

#ifdef ISC_PLATFORM_USETHREADS
static isc_threadresult_t
#ifdef _WIN32
WINAPI
#endif
run(void *uap) {
    isc_taskmgr_t *manager = uap;

    XTHREADTRACE(isc_msgcat_get(isc_msgcat, ISC_MSGSET_GENERAL,
                    ISC_MSG_STARTING, "starting"));

    dispatch(manager);

    XTHREADTRACE(isc_msgcat_get(isc_msgcat, ISC_MSGSET_GENERAL,
                    ISC_MSG_EXITING, "exiting"));

    return ((isc_threadresult_t)0);
}
#endif /* ISC_PLATFORM_USETHREADS */

static void
manager_free(isc_taskmgr_t *manager) {
    isc_mem_t *mctx;

#ifdef ISC_PLATFORM_USETHREADS
    (void)isc_condition_destroy(&manager->work_available);
    isc_mem_put(manager->mctx, manager->threads,
            manager->workers * sizeof (isc_thread_t));
#endif /* ISC_PLATFORM_USETHREADS */
    DESTROYLOCK(&manager->lock);
    manager->magic = 0;
    mctx = manager->mctx;
    isc_mem_put(mctx, manager, sizeof *manager);
    isc_mem_detach(&mctx);
}

isc_result_t
isc_taskmgr_create(isc_mem_t *mctx, unsigned int workers,
           unsigned int default_quantum, isc_taskmgr_t **managerp)
{
    unsigned int i, started = 0;
    isc_taskmgr_t *manager;

    /*
     * Create a new task manager.
     */

    REQUIRE(workers > 0);
    REQUIRE(managerp != NULL && *managerp == NULL);

#ifndef ISC_PLATFORM_USETHREADS
    UNUSED(i);
    UNUSED(started);
    UNUSED(workers);

    if (taskmgr != NULL) {
        taskmgr->refs++;
        *managerp = taskmgr;
        return (ISC_R_SUCCESS);
    }
#endif /* ISC_PLATFORM_USETHREADS */

    manager = isc_mem_get(mctx, sizeof *manager);
    if (manager == NULL)
        return (ISC_R_NOMEMORY);
    manager->magic = TASK_MANAGER_MAGIC;
    manager->mctx = NULL;
    manager->workers = 0;
    if (isc_mutex_init(&manager->lock) != ISC_R_SUCCESS) {
        isc_mem_put(mctx, manager, sizeof *manager);
        UNEXPECTED_ERROR(__FILE__, __LINE__,
                 "isc_mutex_init() %s",
                 isc_msgcat_get(isc_msgcat, ISC_MSGSET_GENERAL,
                        ISC_MSG_FAILED, "failed"));
        return (ISC_R_UNEXPECTED);
    }
#ifdef ISC_PLATFORM_USETHREADS
    manager->threads = isc_mem_get(mctx, workers * sizeof (isc_thread_t));
    if (manager->threads == NULL) {
        DESTROYLOCK(&manager->lock);
        isc_mem_put(mctx, manager, sizeof *manager);
        return (ISC_R_NOMEMORY);
    }
    if (isc_condition_init(&manager->work_available) != ISC_R_SUCCESS) {
        DESTROYLOCK(&manager->lock);
        isc_mem_put(mctx, manager->threads,
                workers * sizeof (isc_thread_t));
        isc_mem_put(mctx, manager, sizeof *manager);
        UNEXPECTED_ERROR(__FILE__, __LINE__,
                 "isc_condition_init() %s",
                 isc_msgcat_get(isc_msgcat, ISC_MSGSET_GENERAL,
                        ISC_MSG_FAILED, "failed"));
        return (ISC_R_UNEXPECTED);
    }
#endif /* ISC_PLATFORM_USETHREADS */
    if (default_quantum == 0)
        default_quantum = DEFAULT_DEFAULT_QUANTUM;
    manager->default_quantum = default_quantum;
    INIT_LIST(manager->tasks);
    INIT_LIST(manager->ready_tasks);
    manager->exiting = ISC_FALSE;
    manager->workers = 0;

    isc_mem_attach(mctx, &manager->mctx);

#ifdef ISC_PLATFORM_USETHREADS
    LOCK(&manager->lock);
    /*
     * Start workers.
     */
    for (i = 0; i < workers; i++) {
        if (isc_thread_create(run, manager,
                      &manager->threads[manager->workers]) ==
            ISC_R_SUCCESS) {
            manager->workers++;
            started++;
        }
    }
    UNLOCK(&manager->lock);

    if (started == 0) {
        manager_free(manager);
        return (ISC_R_NOTHREADS);
    }
    isc_thread_setconcurrency(workers);
#else /* ISC_PLATFORM_USETHREADS */
    manager->refs = 0;
    taskmgr = manager;
#endif /* ISC_PLATFORM_USETHREADS */

    *managerp = manager;

    return (ISC_R_SUCCESS);
}

void
isc_taskmgr_destroy(isc_taskmgr_t **managerp) {
    isc_taskmgr_t *manager;
    isc_task_t *task;
    unsigned int i;

    /*
     * Destroy '*managerp'.
     */

    REQUIRE(managerp != NULL);
    manager = *managerp;
    REQUIRE(VALID_MANAGER(manager));

#ifndef ISC_PLATFORM_USETHREADS
    UNUSED(i);

    if (manager->refs > 1) {
        manager->refs--;
        *managerp = NULL;
        return;
    }
#endif /* ISC_PLATFORM_USETHREADS */

    XTHREADTRACE("isc_taskmgr_destroy");
    /*
     * Only one non-worker thread may ever call this routine.
     * If a worker thread wants to initiate shutdown of the
     * task manager, it should ask some non-worker thread to call
     * isc_taskmgr_destroy(), e.g. by signalling a condition variable
     * that the startup thread is sleeping on.
     */

    /*
     * Unlike elsewhere, we're going to hold this lock a long time.
     * We need to do so, because otherwise the list of tasks could
     * change while we were traversing it.
     *
     * This is also the only function where we will hold both the
     * task manager lock and a task lock at the same time.
     */

    LOCK(&manager->lock);

    /*
     * Make sure we only get called once.
     */
    INSIST(!manager->exiting);
    manager->exiting = ISC_TRUE;

    /*
     * Post shutdown event(s) to every task (if they haven't already been
     * posted).
     */
    for (task = HEAD(manager->tasks);
         task != NULL;
         task = NEXT(task, link)) {
        LOCK(&task->lock);
        if (task_shutdown(task))
            ENQUEUE(manager->ready_tasks, task, ready_link);
        UNLOCK(&task->lock);
    }
#ifdef ISC_PLATFORM_USETHREADS
    /*
     * Wake up any sleeping workers.  This ensures we get work done if
     * there's work left to do, and if there are already no tasks left
     * it will cause the workers to see manager->exiting.
     */
    BROADCAST(&manager->work_available);
    UNLOCK(&manager->lock);

    /*
     * Wait for all the worker threads to exit.
     */
    for (i = 0; i < manager->workers; i++)
        (void)isc_thread_join(manager->threads[i], NULL);
#else /* ISC_PLATFORM_USETHREADS */
    /*
     * Dispatch the shutdown events.
     */
    UNLOCK(&manager->lock);
    while (isc__taskmgr_ready())
        (void)isc__taskmgr_dispatch();
#endif /* ISC_PLATFORM_USETHREADS */

    manager_free(manager);

    *managerp = NULL;
}

#ifndef ISC_PLATFORM_USETHREADS
isc_boolean_t
isc__taskmgr_ready(void) {
    if (taskmgr == NULL)
        return (ISC_FALSE);
    return (ISC_TF(!ISC_LIST_EMPTY(taskmgr->ready_tasks)));
}

isc_result_t
isc__taskmgr_dispatch(void) {
    isc_taskmgr_t *manager = taskmgr;

    if (taskmgr == NULL)
        return (ISC_R_NOTFOUND);

    dispatch(manager);

    return (ISC_R_SUCCESS);
}
#endif /* ISC_PLATFORM_USETHREADS */