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