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 Lesser 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 Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
  21  * USA
  22  */
  23
  24 #ifdef HAVE_CONFIG_H
  25 #include <config.h>
  26 #endif
  27
  28 #include <stdio.h>
  29 #include <pthread.h>
  30
  31 #include <glib.h>
  32 #include <glib/gi18n-lib.h>
  33
  34 #include <libedataserver/e-memory.h>
  35
  36 #include "camel-debug.h"
  37 #include "camel-exception.h"
  38
  39 /* dont turn this off */
  40 #define w(x) x
  41
  42 /* i dont know why gthread_mutex stuff even exists, this is easier */
  43
  44 /* also, i'm not convinced mutexes are needed here.  But it
  45    doesn't really hurt either */
  46 static pthread_mutex_t exception_mutex = PTHREAD_MUTEX_INITIALIZER;
  47
  48 #define CAMEL_EXCEPTION_LOCK(e) (pthread_mutex_lock(&exception_mutex))
  49 #define CAMEL_EXCEPTION_UNLOCK(e) (pthread_mutex_unlock(&exception_mutex))
  50
  51 static EMemChunk *exception_chunks = NULL;
  52
  53 /**
  54  * camel_exception_new: allocate a new exception object.
  55  *
  56  * Create and returns a new exception object.
  57  *
  58  * Returns the newly allocated exception object
  59  **/
  60 CamelException *
  61 camel_exception_new (void)
  62 {
  63         CamelException *ex;
  64
  65         CAMEL_EXCEPTION_LOCK(exception);
  66
  67         if (exception_chunks == NULL)
  68                 exception_chunks = e_memchunk_new(16, sizeof(CamelException));
  69
  70         ex = e_memchunk_alloc(exception_chunks);
  71         ex->desc = NULL;
  72
  73         /* set the Exception Id to NULL */
  74         ex->id = CAMEL_EXCEPTION_NONE;
  75
  76         CAMEL_EXCEPTION_UNLOCK(exception);
  77
  78         return ex;
  79 }
  80
  81 /**
  82  * camel_exception_init:
  83  * @ex: a #CamelException
  84  *
  85  * Init an exception. This routine is mainly useful when using a
  86  * statically allocated exception.
  87  **/
  88 void
  89 camel_exception_init (CamelException *ex)
  90 {
  91         ex->desc = NULL;
  92
  93         /* set the Exception Id to NULL */
  94         ex->id = CAMEL_EXCEPTION_NONE;
  95 }
  96
  97
  98 /**
  99  * camel_exception_clear:
 100  * @ex: a #CamelException
 101  *
 102  * Clear an exception, that is, set the exception ID to
 103  * #CAMEL_EXCEPTION_NONE and free the description text.  If the
 104  * exception is %NULL, this funtion just returns.
 105  **/
 106 void
 107 camel_exception_clear (CamelException *exception)
 108 {
 109         if (!exception)
 110                 return;
 111
 112         CAMEL_EXCEPTION_LOCK(exception);
 113
 114         if (exception->desc)
 115                 g_free (exception->desc);
 116         exception->desc = NULL;
 117         exception->id = CAMEL_EXCEPTION_NONE;
 118
 119         CAMEL_EXCEPTION_UNLOCK(exception);
 120 }
 121
 122 /**
 123  * camel_exception_free:
 124  * @ex: a #CamelException
 125  *
 126  * Free an exception object. If the exception is %NULL, nothing is
 127  * done, the routine simply returns.
 128  **/
 129 void
 130 camel_exception_free (CamelException *exception)
 131 {
 132         if (!exception)
 133                 return;
 134
 135         if (exception->desc)
 136                 g_free (exception->desc);
 137
 138         CAMEL_EXCEPTION_LOCK(exception);
 139
 140         e_memchunk_free(exception_chunks, exception);
 141
 142         CAMEL_EXCEPTION_UNLOCK(exception);
 143 }
 144
 145 /**
 146  * camel_exception_set: set an exception
 147  * @ex: a #CamelException
 148  * @id: exception id
 149  * @desc: textual description of the exception
 150  *
 151  * Set the value of an exception. The exception id is
 152  * a unique number representing the exception. The
 153  * textual description is a small text explaining
 154  * what happened and provoked the exception.
 155  *
 156  * When @ex is %NULL, nothing is done, this routine
 157  * simply returns.
 158  **/
 159 void
 160 camel_exception_set (CamelException *ex, ExceptionId id, const char *desc)
 161 {
 162         if (camel_debug("exception"))
 163                 printf("CamelException.set(%p, %u, '%s')\n", ex, id, desc);
 164
 165         if (!ex)
 166                 return;
 167
 168         CAMEL_EXCEPTION_LOCK(exception);
 169
 170         ex->id = id;
 171
 172         if (desc != ex->desc) {
 173                 g_free (ex->desc);
 174                 ex->desc = g_strdup (desc);
 175         }
 176
 177         CAMEL_EXCEPTION_UNLOCK(exception);
 178 }
 179
 180 /**
 181  * camel_exception_setv: set an exception
 182  * @ex: a #CamelException
 183  * @id: exception id
 184  * @format: format of the description string. The format string is
 185  * used as in printf().
 186  *
 187  * Set the value of an exception. The exception id is
 188  * a unique number representing the exception. The
 189  * textual description is a small text explaining
 190  * what happened and provoked the exception.
 191  * In this version, the string is created from the format
 192  * string and the variable argument list.
 193  *
 194  * It is safe to say:
 195  *   camel_exception_setv (ex, ..., camel_exception_get_description (ex), ...);
 196  *
 197  * When @ex is %NULL, nothing is done, this routine
 198  * simply returns.
 199  **/
 200 void
 201 camel_exception_setv (CamelException *ex, ExceptionId id, const char *format, ...)
 202 {
 203         va_list args;
 204         char *desc;
 205
 206         va_start(args, format);
 207         desc = g_strdup_vprintf (format, args);
 208         va_end (args);
 209
 210         if (camel_debug("exception"))
 211                 printf("CamelException.setv(%p, %u, '%s')\n", ex, id, desc);
 212
 213         if (!ex) {
 214                 g_free(desc);
 215                 return;
 216         }
 217
 218         CAMEL_EXCEPTION_LOCK(exception);
 219
 220         g_free(ex->desc);
 221         ex->desc = desc;
 222         ex->id = id;
 223
 224         CAMEL_EXCEPTION_UNLOCK(exception);
 225 }
 226
 227 /**
 228  * camel_exception_xfer:
 229  * @ex_dst: Destination exception object
 230  * @ex_src: Source exception object
 231  *
 232  * Transfer the content of an exception from an exception object to
 233  * another.  The destination exception receives the id and the
 234  * 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                 w(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:
 267  * @ex: a #CamelException
 268  *
 269  * Get the id of an exception.
 270  *
 271  * Returns the exception id (#CAMEL_EXCEPTION_NONE will be returned if
 272  * @ex is %NULL or unset)
 273  **/
 274 ExceptionId
 275 camel_exception_get_id (CamelException *ex)
 276 {
 277         if (ex)
 278                 return ex->id;
 279
 280         w(g_warning ("camel_exception_get_id called with NULL parameter."));
 281
 282         return CAMEL_EXCEPTION_NONE;
 283 }
 284
 285 /**
 286  * camel_exception_get_description:
 287  * @ex: a #CamelException
 288  *
 289  * Get the exception description text.
 290  *
 291  * Returns the exception description text (%NULL will be returned if
 292  * @ex is %NULL or unset)
 293  **/
 294 const gchar *
 295 camel_exception_get_description (CamelException *ex)
 296 {
 297         char *ret = NULL;
 298
 299         if (ex)
 300                 ret = ex->desc;
 301         else
 302                 w(g_warning ("camel_exception_get_description called with NULL parameter."));
 303
 304         return ret ? ret : (_("No description available"));
 305 }