thread_finalizer.cpp

00001 
00002 /***************************************************************************
00003  *  thread_finalizer.cpp - Thread finalizer interface
00004  *
00005  *  Created: Fri Jan 12 13:29:29 2007
00006  *  Copyright  2006-2007 Tim Niemueller [www.niemueller.de]
00007  *
00008  ****************************************************************************/
00009 
00010 /*  This program is free software; you can redistribute it and/or modify
00011  *  it under the terms of the GNU General Public License as published by
00012  *  the Free Software Foundation; either version 2 of the License, or
00013  *  (at your option) any later version. A runtime exception applies to
00014  *  this software (see LICENSE.GPL_WRE file mentioned below for details).
00015  *
00016  *  This program is distributed in the hope that it will be useful,
00017  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  *  GNU Library General Public License for more details.
00020  *
00021  *  Read the full text in the LICENSE.GPL_WRE file in the doc directory.
00022  */
00023 
00024 #include <core/threading/thread_finalizer.h>
00025 
00026 namespace fawkes {
00027 
00028 /** @class CannotFinalizeThreadException core/threading/thread_finalizer.h
00029  * Thread cannot be finalized.
00030  * Thrown if a thread could not be finalized for whatever reason.
00031  * @ingroup Exceptions
00032  */
00033 
00034 /** Constructor.
00035  * @param format message format (reason or symptom of failure)
00036  */
00037 CannotFinalizeThreadException::CannotFinalizeThreadException(const char *format, ...)
00038   : Exception()
00039 {
00040   va_list va;
00041   va_start(va, format);
00042   append_va(format, va);
00043   va_end(va);
00044 }
00045 
00046 /** Constructor.
00047  * @param e exception to copy messages from
00048  */
00049 CannotFinalizeThreadException::CannotFinalizeThreadException(Exception &e)
00050   : Exception(e)
00051 {
00052 }
00053 
00054 
00055 /** @class ThreadFinalizer core/threading/thread_finalizer.h
00056  * Thread finalizer interface.
00057  * This interface is used by the ThreadManager. The finalize() method is called
00058  * for each thread that is about to be removed. If there are any special needs
00059  * that have to be finalized before the thread is stopped on the given real
00060  * classes of the thread this is the way to do it.
00061  *
00062  * The finalizer may abort the stopping of a thread by throwing a
00063  * CannotFinalizeThreadException. This can for example be used if you have two
00064  * threads A and B. A depends on B in that B is needed for A to run properly.
00065  * Now both threads are running and then B is called to stop. The finalize will
00066  * call threads B finalize() method, which fails (because it knows about the
00067  * dependency of A for example by some kind of register pattern). This tells the
00068  * thread manager not to stop B, because this would break A.
00069  *
00070  * See Fawkes main application for
00071  * an example.
00072  * @author Tim Niemueller
00073  *
00074  * @fn bool ThreadFinalizer::prepare_finalize(Thread *thread) = 0
00075  * Prepare finalization of a thread.
00076  * If the finalizer needs to do anything to prepare a maybe following finalize()
00077  * can do so here. This is also the only place where it proclaim that finalizing
00078  * the given thread at the given time is unsafe.
00079  * The finalizer shall NOT call Thread::prepare_finalize().
00080  * @param thread thread to prepare finalization for
00081  * @return true if nothing prevents finalization, false otherwise
00082  * @see Thread::prepare_finalize()
00083  * 
00084  *
00085  * @fn void ThreadFinalizer::finalize(Thread *thread) = 0
00086  * Finalize a thread.
00087  * This method is called by the ThreadManager for each Thread that is to be
00088  * stopped and removed from the list of running threads.
00089  * The finalizer shall NOT call Thread::finalize().
00090  * @param thread thread to finalize.
00091  * @exception CannotFinalizeThread thrown if thread can for not b finalized
00092  * @see Thread::finalize()
00093  */
00094 
00095 /** Virtual empty destructor. */
00096 ThreadFinalizer::~ThreadFinalizer()
00097 {
00098 }
00099 
00100 
00101 } // end namespace fawkes