http://www.ousob.com --- Legacy Redefined OuSob - File: /wwwroot/clipx/usr/include/wvstreams/wvsubprocqueue.h

/* -*- Mode: C++ -*- * Worldvisions Weaver Software: * Copyright (C) 1997-2002 Net Integration Technologies, Inc. * * A class for running a series or set of processes, one at a time. */ #ifndef __WVSUBPROCQUEUE_H #define __WVSUBPROCQUEUE_H #include "wvsubproc.h" /** * An ordered queue of WvSubProc instances. * * You can enqueue any number of subprocesses to run sequentially, with * a specified maximum number of processes running at a time. The processes * run in the order they are added to the queue, except that (of course) * running more than one process at a time may cause processes to overlap * in an undefined way. * * You can define "sync point" subprocesses using the "cookie" parameter to * add(). A sync point is guaranteed to be started: * - alone, not in parallel with anything else * - at least once after you enqueue it * - at least once after every already-enqueued process has finished * - immediately after every already-enqueued process has finished, *unless* * an earlier sync point is still waiting. * - no more than twice after the final time it is enqueued. * * That sounds complicated, but it lets you easily implement a common * type of "delayed event" queuing: "Some time after each of these * things S, I need to run X, but I don't need to run it for *every* * element of S, but I don't want it to wait forever because I keep adding * to S." * * For example, imagine you have one type of operation, add() that * creates a new file in a directory, and another type of operation * that regenerates the directory index. You need to generate the * index after any create operation before it will really be done, * but there is no need to generate the index more than once when * doing a lot of create operations. You could do a sequence like * this: * * for (i = 0; i < 10; i++) * { add_file(i); } * * Where "add" can trivially just do q.add(NULL, whatever1) and then * q.add(&reindex_cookie, whatever2). WvSubProcQueue * will ensure that "whatever2" runs as soon as possible (to prevent * arbitrary delays because of nonstop add_file() calls) and also exactly * once at the very end, but not every single time. * * In case it wasn't obvious, if you create more than one * WvSubProcQueue, they operate totally independently of each other. That * means if you have two queues with a max of 10 processes, you might have * up to 20 processes running at a time. */ class WvSubProcQueue { public: /** * Create a WvSubProcQueue. _maxrunning is the maximum number of * processes to have running in parallel. 1 is usually a good choice. */ WvSubProcQueue(unsigned _maxrunning); virtual ~WvSubProcQueue(); /** * Enqueue a process. If cookie is NULL, the process will simply * be added at the end of the queue. If cookie is non-NULL, it will * be treated as a "sync point" as described above. * * WARNING! Do not start_again() the proc before passing it to the * WvSubProcQueue. This is done automatically in some WvSubProc * constructors. Use WvSubProc::prepare() or preparev() instead. */ void add(void *cookie, WvSubProc *proc); /** * Like add(cookie, proc) but you don't have to build the WvSubProc * yourself for simple cases. */ void add(void *cookie, const char *cmd, const char * const *argv); /** * Clean up after any running processes in the queue, and start running * additional processes if any are waiting. Never blocks. * * Returns the number of new processes which were started on this run. * * WARNING: you must call this rather often in order to keep your * queue moving. */ int go(); /** * Wait synchronously for all processes in the entire queue to finish. * This might block forever!! You should probably only call it in * test programs or if you really know what you're doing. Otherwise * just call go() occasionally. */ void finish(); /// Return the number of currently running processes. unsigned running() const; /// Return the number of unfinished (ie. running or waiting) processes. unsigned remaining() const; /// True if there are no unfinished (ie. running *or* waiting) processes. bool isempty() const; private: struct Ent { Ent(void *_cookie, WvSubProc *_proc) { cookie = _cookie; proc = _proc; redo = false; } ~Ent() { if (proc) delete proc; } void *cookie; WvSubProc *proc; bool redo; }; DeclareWvList(Ent); unsigned maxrunning; EntList runq, waitq; bool cookie_running(); }; #endif // __WVSUBPROCQUEUE_H