camel/camel-exception.c

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
   2 /*
   3  *
   4  * Author :
   5  *  Bertrand Guiheneuf <bertrand@helixcode.com>
   6  *
   7  * Copyright 1999-2003 Ximian, Inc. (www.ximian.com)
   8  *
   9  * This program is free software; you can redistribute it and/or
  10  * modify it under the terms of version 2 of the GNU General Public
  11  * License as published by the Free Software Foundation.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  21  * USA
  22  */
  23
  24 #ifdef HAVE_CONFIG_H
  25 #include <config.h>
  26 #endif
  27
  28 #include <glib.h>
  29 #include <pthread.h>
  30
  31 #include "camel-exception.h"
  32 #include "e-util/e-memory.h"
  33
  34 /* i dont know why gthread_mutex stuff even exists, this is easier */
  35
  36 /* also, i'm not convinced mutexes are needed here.  But it
  37    doesn't really hurt either */
  38 static pthread_mutex_t exception_mutex = PTHREAD_MUTEX_INITIALIZER;
  39
  40 #define CAMEL_EXCEPTION_LOCK(e) (pthread_mutex_lock(&exception_mutex))
  41 #define CAMEL_EXCEPTION_UNLOCK(e) (pthread_mutex_unlock(&exception_mutex))
  42
  43 static EMemChunk *exception_chunks = NULL;
  44
  45 /**
  46  * camel_exception_new: allocate a new exception object.
  47  *
  48  * Create and returns a new exception object.
  49  *
  50  *
  51  * Return value: The newly allocated exception object.
  52  **/
  53 CamelException *
  54 camel_exception_new (void)
  55 {
  56         CamelException *ex;
  57
  58         CAMEL_EXCEPTION_LOCK(exception);
  59
  60         if (exception_chunks == NULL)
  61                 exception_chunks = e_memchunk_new(16, sizeof(CamelException));
  62
  63         ex = e_memchunk_alloc(exception_chunks);
  64         ex->desc = NULL;
  65
  66         /* set the Exception Id to NULL */
  67         ex->id = CAMEL_EXCEPTION_NONE;
  68
  69         CAMEL_EXCEPTION_UNLOCK(exception);
  70
  71         return ex;
  72 }
  73
  74 /**
  75  * camel_exception_init: init a (statically allocated) exception.
  76  *
  77  * Init an exception. This routine is mainly
  78  * useful when using a statically allocated
  79  * exception.
  80  *
  81  *
  82  **/
  83 void
  84 camel_exception_init (CamelException *ex)
  85 {
  86         ex->desc = NULL;
  87
  88         /* set the Exception Id to NULL */
  89         ex->id = CAMEL_EXCEPTION_NONE;
  90 }
  91
  92
  93 /**
  94  * camel_exception_clear: Clear an exception
  95  * @exception: the exception object
  96  *
  97  * Clear an exception, that is, set the
  98  * exception ID to CAMEL_EXCEPTION_NONE and
  99  * free the description text.
 100  * If the exception is NULL, this funtion just
 101  * returns.
 102  **/
 103 void
 104 camel_exception_clear (CamelException *exception)
 105 {
 106         if (!exception)
 107                 return;
 108
 109         CAMEL_EXCEPTION_LOCK(exception);
 110
 111         if (exception->desc)
 112                 g_free (exception->desc);
 113         exception->desc = NULL;
 114         exception->id = CAMEL_EXCEPTION_NONE;
 115
 116         CAMEL_EXCEPTION_UNLOCK(exception);
 117 }
 118
 119 /**
 120  * camel_exception_free: Free an exception
 121  * @exception: The exception object to free
 122  *
 123  * Free an exception object. If the exception
 124  * is NULL, nothing is done, the routine simply
 125  * returns.
 126  **/
 127 void
 128 camel_exception_free (CamelException *exception)
 129 {
 130         if (!exception)
 131                 return;
 132
 133         if (exception->desc)
 134                 g_free (exception->desc);
 135
 136         CAMEL_EXCEPTION_LOCK(exception);
 137
 138         e_memchunk_free(exception_chunks, exception);
 139
 140         CAMEL_EXCEPTION_UNLOCK(exception);
 141 }
 142
 143 /**
 144  * camel_exception_set: set an exception
 145  * @ex: exception object
 146  * @id: exception id
 147  * @desc: textual description of the exception
 148  *
 149  * Set the value of an exception. The exception id is
 150  * a unique number representing the exception. The
 151  * textual description is a small text explaining
 152  * what happened and provoked the exception.
 153  *
 154  * When @ex is NULL, nothing is done, this routine
 155  * simply returns.
 156  *
 157  **/
 158 void
 159 camel_exception_set (CamelException *ex,
 160                      ExceptionId id,
 161                      const char *desc)
 162 {
 163         if (!ex)
 164                 return;
 165
 166         CAMEL_EXCEPTION_LOCK(exception);
 167
 168         ex->id = id;
 169
 170         if (desc != ex->desc) {
 171                 g_free (ex->desc);
 172                 ex->desc = g_strdup (desc);
 173         }
 174
 175         CAMEL_EXCEPTION_UNLOCK(exception);
 176 }
 177
 178 /**
 179  * camel_exception_setv: set an exception
 180  * @ex: exception object
 181  * @id: exception id
 182  * @format: format of the description string. The format string is
 183  * used as in printf().
 184  *
 185  * Set the value of an exception. The exception id is
 186  * a unique number representing the exception. The
 187  * textual description is a small text explaining
 188  * what happened and provoked the exception.
 189  * In this version, the string is created from the format
 190  * string and the variable argument list.
 191  *
 192  * It is safe to say:
 193  *   camel_exception_setv (ex, ..., camel_exception_get_description (ex), ...);
 194  *
 195  * When @ex is NULL, nothing is done, this routine
 196  * simply returns.
 197  *
 198  **/
 199 void
 200 camel_exception_setv (CamelException *ex,
 201                       ExceptionId id,
 202                       const char *format,
 203                       ...)
 204 {
 205         va_list args;
 206         char *old;
 207
 208         if (!ex)
 209                 return;
 210
 211         CAMEL_EXCEPTION_LOCK(exception);
 212
 213         old = ex->desc;
 214
 215         va_start(args, format);
 216         ex->desc = g_strdup_vprintf (format, args);
 217         va_end (args);
 218
 219         g_free (old);
 220
 221         ex->id = id;
 222
 223         CAMEL_EXCEPTION_UNLOCK(exception);
 224 }
 225
 226 /**
 227  * camel_exception_xfer: transfer an exception
 228  * @ex_dst: Destination exception object
 229  * @ex_src: Source exception object
 230  *
 231  * Transfer the content of an exception from
 232  * an exception object to another.
 233  * The destination exception receives the id and
 234  * the description text of the source exception.
 235  **/
 236 void
 237 camel_exception_xfer (CamelException *ex_dst,
 238                       CamelException *ex_src)
 239 {
 240         if (ex_src == NULL) {
 241                 g_warning ("camel_exception_xfer: trying to transfer NULL exception to %p\n", ex_dst);
 242                 return;
 243         }
 244
 245         if (ex_dst == NULL) {
 246                 /* must have same side-effects */
 247                 camel_exception_clear (ex_src);
 248                 return;
 249         }
 250
 251         CAMEL_EXCEPTION_LOCK(exception);
 252
 253         if (ex_dst->desc)
 254                 g_free (ex_dst->desc);
 255
 256         ex_dst->id = ex_src->id;
 257         ex_dst->desc = ex_src->desc;
 258
 259         ex_src->desc = NULL;
 260         ex_src->id = CAMEL_EXCEPTION_NONE;
 261
 262         CAMEL_EXCEPTION_UNLOCK(exception);
 263 }
 264
 265 /**
 266  * camel_exception_get_id: get the exception id
 267  * @ex: The exception object
 268  *
 269  * Return the id of an exception.
 270  * If @ex is NULL, return CAMEL_EXCEPTION_NONE;
 271  *
 272  * Return value: Exception ID.
 273  **/
 274 ExceptionId
 275 camel_exception_get_id (CamelException *ex)
 276 {
 277         if (ex)
 278                 return ex->id;
 279         else {
 280                 g_warning ("camel_exception_get_id called with NULL parameter.");
 281                 return CAMEL_EXCEPTION_NONE;
 282         }
 283 }
 284
 285 /**
 286  * camel_exception_get_description: get the description of an exception.
 287  * @ex: The exception object
 288  *
 289  * Return the exception description text.
 290  * If @ex is NULL, return NULL;
 291  *
 292  *
 293  * Return value: Exception description text.
 294  **/
 295 const gchar *
 296 camel_exception_get_description (CamelException *ex)
 297 {
 298         char *ret = NULL;
 299
 300         if (ex)
 301                 ret = ex->desc;
 302         else
 303                 g_warning ("camel_exception_get_description called with NULL parameter.");
 304
 305         return ret;
 306 }