/**
 * \file    exception.c
 * \author  Georg Steffers <georg@steffers.org>
 * \brief   The core of the exception system implemented within libscot.
 *
 * This file has all implementations for the exception system of scot.
 * It defines the exception_t structure which holds basic information
 * about an exception. Instances of this structure are organized
 * in a queue that is part of excenv_t. That stucture describes the environment
 * in which exceptions may occure, that is a TRY-CATCH block.
 * Every TRY creates a new excenv_t instance and puts them in a stack,
 * every CATCH get one excenv_t from that stack.
 * To achive threadsaveness those excenv_t stack is organized within
 * thread_excenv_t which associates a thread-id to an excenv_t stack.
 * Thus every stack has its own exception stack.
 *
 * Copyright (C)2006    Georg Steffers <georg@steffers.org>
 * 
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <setjmp.h>
#include <string.h>

/**
 * \internal
 * \brief We need direct access to elements of struct excenv_t.
 */
#define  USE_SCOT_STRUCT_EXCENV_T
/**
 * \internal
 * \brief We need direct access to elements of struct exception_t.
 */
#define  USE_SCOT_STRUCT_EXCEPTION_T
#include <scot/exception.h>
#undef   USE_SCOT_STRUCT_EXCENV_T
#undef   USE_SCOT_STRUCT_EXCEPTION_T

#include <scot/thread.h>           /* for SELF_THREAD and THREAD_T macro */
#include <scot/memory.h>           /* for windows threadsafe memory functions */

/**
 * \internal
 * \brief Don't use exceptions in the list code.
 *
 * as the code here provides the exception system it is not very wise to
 * use exceptions in this code, Thus this define deactivates exception
 * support within the code generation macros defined in \link scot/list.h
 * scot/list.h\endlink.
 */
#define  USE_NO_EXCEPTION
/**
 * \internal
 * \brief make list functions static for this file.
 *
 * All list, stack and queue stuff for exception structures is only needed
 * here and not very likely to be needed anywhere else in the code.
 * Thus generate them static, (said with GEN_LOCAL)
 */
#define  GEN_LOCAL
#include <scot/list.h>
#include <scot/stack.h>
#include <scot/queue.h>
#undef   GEN_LOCAL
#undef   USE_NO_EXCEPTION

#include <scot_common.h>

/************************************************************************
 * Generation of typesafe functions to handle lists of the types        *
 ************************************************************************/
GEN_LIST             (exception_t);
GEN_QUEUE_FUNC_PROTO (exception_t);
GEN_QUEUE_IMPL       (exception_t);
GEN_LIST             (excenv_t);
GEN_STACK            (excenv_t);

/**
 * \internal
 * Structure to assign every thread an own exception environment stack.
 */
struct thread_excenv_t
{
   THREAD_T                thread_handle;         /**< Current thread-id */
   stack_excenv_t_node_t   *ee_stack;   /**< The exception environment stack */
};
typedef struct thread_excenv_t thread_excenv_t;
GEN_LIST             (thread_excenv_t);

/** 
 * \internal
 * \brief If we use threads this is the root of all exception environments.
 */
list_thread_excenv_t_node_t   *tee_list = NULL;
/** 
 * \internal
 * \brief If we don't use threads this is the root of all exception
 *        environments.
 */
stack_excenv_t_node_t         *ee_stack = NULL;

/************************************************************************
 * static helper                                                        *
 ************************************************************************/
/**
 * \internal
 * \param   a     instance to be compared
 * \param   b     instance to be compared
 * \pre           None
 * \return A value greater than, equal or less than 0 as with strcmp.
 * \retval  <0    if a->thread_handle is less than b->thread_handle
 * \retval  >0    if a->thread_handle is greater than b->thread_handle
 * \retval  ==0   if a->thread_handle is equal to b->thread_handle
 * \post          None
 *
 * \brief Comparison for instances of thread_excenv_t.
 *
 * This is a comparison function for instances of thread_excenv_t. They are
 * assumed equal if both thread_excenv_t::thread_handle are equal.
 * The function follows the same scheme as for example strcmp.
 */
static
int
compare_thread_excenv_t (const thread_excenv_t *a , const thread_excenv_t *b)
{
   return ! THREAD_EQUAL (a->thread_handle, b->thread_handle);
}

/**
 * \internal
 * \param   e    an instance of thread_excenv_t
 * \pre     \a e has to be initialize correctly previous to this call.
 * \return  Nothing
 * \post    The memory needed by \a e is correctly freed.
 *
 * \brief   Destructor for thread_excenv_t instances.
 *
 * This cleanly frees an instance of thread_excenv_t.
 */
static
void
free_thread_excenv_t (thread_excenv_t *e)
{
   stack_excenv_t_free (e->ee_stack);
   SCOT_MEM_FREE (e);
}

/**
 * \internal
 * \param   e    an instance of excenv_t
 * \pre     \a e has to be initialize correctly previous to this call.
 * \return  Nothing
 * \post    The memory needed by \a e is correctly freed.
 *
 * \brief   Destructor for excenv_t instances.
 *
 * This cleanly frees an instance of excenv_t.
 */
static
void
free_excenv_t (excenv_t *e)
{
   queue_exception_t_free (e->e_queue);
   SCOT_MEM_FREE (e);
}

/**
 * \internal
 * \param   e    an instance of exception_t
 * \pre     \a e has to be initialize correctly previous to this call.
 * \return  Nothing
 * \post    The memory needed by \a e is correctly freed.
 *
 * \brief   Destructor for exception_t instances.
 *
 * This cleanly frees an instance of exception_t.
 */
static
void
free_exception_t (exception_t * e)
{
   SCOT_MEM_FREE (e);
}



/************************************************************************
 * interface implementtaion                                             *
 ************************************************************************/
/**
 * \internal
 * \pre     No threads are used.
 * \return  Nothing
 * \post    None
 *
 * \brief   initializes the root of all exception environments for non
 *          threaded code.
 *
 * This is called within the TRY, CATCH macros to ensure that the correct
 * exception environment stack for the current thread is used.
 * \nWell, we don't have threads when this is used, so it just returns
 * ee_stack if it has initialized it previously.
 */
void *
exc_init (void)
{
	/*
	 * If threads are used already, use them further on.
	 * (If there is a threaded_exception list tee_list).
	 */
   if (tee_list != NULL)
		return threaded_exc_init ();

   if (ee_stack != NULL)
      return (void *) ee_stack;

   ee_stack = stack_excenv_t_new (ee_stack);

   bindtextdomain (PACKAGE, LOCALEDIR);

   if (ee_stack == NULL)
      /* FIXME: make output to syslog or something... */
   {
      char buf[1024];

      sprintf (
            buf,
            "[Fatal(exception.c:97)]\n%s",
            D_("exc_init failed"));
      perror (buf);
      abort ();
   }

   return (void *) ee_stack;
}

/**
 * \internal
 * \pre     Threads are used.
 * \return  Nothing
 * \post    None
 *
 * \brief   initializes the root of all exception environments for non
 *          threaded code.
 *
 * This is called within the TRY, CATCH macros to ensure that the correct
 * exception environment stack for the current thread is used.
 */
void *
threaded_exc_init (void)
{
   list_thread_excenv_t_node_t   *tee_l;
   thread_excenv_t               *tee;
   THREAD_T                      t;

   t = SELF_THREAD;

   bindtextdomain (PACKAGE, LOCALEDIR);

   /*
    * First create the list if it does not exist at all and
    * set the comparison function.
    */
   if (tee_list == NULL)
   {
      tee_list = list_thread_excenv_t_new (tee_list);
      list_thread_excenv_t_set_cmp (compare_thread_excenv_t);
   }

   /*
    * Now a little trick: As i compare thread_excenv_t by comparing its
    * first element thread_excenv_t->thread_handle and don't use any other part of
    * this struct with a compare i can cast THREAD_T * to thread_excenv_t *
    * to check for the existance of an entry in the list.
    */
   tee_l = list_thread_excenv_t_find (tee_list, (thread_excenv_t *) &t);

   /*
    * if tee_l != NULL we have found a previosly initialized stack, good!
    * Return the excenv_t we have to use.
    */
   if (tee_l != NULL)
      return (void *) list_thread_excenv_t_retrive (tee_l)->ee_stack;

   /*
    * else we must create a new entry.
    */
   tee = (thread_excenv_t *) SCOT_MEM_GET (sizeof (struct thread_excenv_t));
   if (tee == NULL)
   {
      char buf[1024];

      sprintf (
            buf,
            "[Fatal(exception.c:97)]\n%s",
            D_("exc_init failed, can't get memory for new list element."));
      perror (buf);
      abort ();
   }

   tee->thread_handle = SELF_THREAD;
   tee->ee_stack = stack_excenv_t_new (tee->ee_stack);

   if (tee->ee_stack == NULL)
      /* FIXME: make output to syslog or something... */
   {
      char buf[1024];

      sprintf (
            buf,
            "[Fatal(exception.c:97)]\n%s",
            D_("exc_init failed"));
      perror (buf);
      abort ();
   }

   list_thread_excenv_t_insert (tee_list, tee);

   return (void *) tee->ee_stack;
}

/**
 * \internal
 * \param   ee_s  the stack of exception environments for the actual
 *                thread.
 * \pre     The root of the exception environments must be initialized
 *          either by exc_init() (if no threads are used) or by 
 *          threaded_exc_init() (if threads are used).
 * \return  Nothing
 * \post    A new exception environment is pushed int the stack of exception
 *          environment (previously called root sometimes) and thus became
 *          current.
 *
 * \brief   creates a new exception environment and pushes it into the root.
 */
void
excenv_new (void *ee_s)
{
   stack_excenv_t_node_t   *ee_stack = (stack_excenv_t_node_t *) ee_s;
   excenv_t                *ee;

   bindtextdomain (PACKAGE, LOCALEDIR);

   ee = (excenv_t *) SCOT_MEM_GET (sizeof (excenv_t));
   if (ee == NULL)
      /* FIXME: make output to syslog or something... */
   {
      char buf[1024];

      sprintf (
            buf,
            "[Fatal(exception.c:113)]\n%s",
            D_("excenv_new failed"));
      perror (buf);
      abort ();
   }

   ee->e_queue = queue_exception_t_new (ee->e_queue);
   if (ee->e_queue == NULL)
      /* FIXME: make output to syslog or something... */
   {
      char buf[1024];

      sprintf (
            buf,
            "[Fatal(exception.c:121)]\n%s",
            D_("excenv_new failed"));
      perror (buf);
      abort ();
   }

   if (stack_excenv_t_push (ee_stack, ee) == NULL)
   {
      char *errmsg;
      char buf[1024];

      errmsg = strerror (errno);

      stack_excenv_t_free (ee_stack);
      SCOT_MEM_FREE (ee);

      sprintf (
            buf,
            "[FATAL(exception.c:101)]\n%s%s",
            D_("could not push the new excenv_t "
               "into ee_stack:\n"),
            errmsg);

      fprintf (stderr, buf);

      abort ();
   }
}

/**
 * \internal
 * \param   ee_s  the stack of exception environments for the actual
 *                thread.
 * \pre     The root of the exception environments must be initialized
 *          either by exc_init() (if no threads are used) or by 
 *          threaded_exc_init() (if threads are used).
 *          There must be an actual exception environment into the stack
 *          of exception environments.
 * \return  a pointer to the jmp_buf variable of the current exception
 *          environment.
 * \post    None
 *
 * \brief   This returns a pointer to the jmp_buf variable of the current
 *          exception environment.
 *
 * A pointer to the jmp_buf variable of the current exception environment is
 * returned for use by the setjmp call in TRY. I tried to call setjmp directly
 * here, but that causes confusion when TRY-CATCH blocks are nested.
 */
jmp_buf *
excenv_jmp_buf (void *ee_s)
{
   stack_excenv_t_node_t   *ee_stack = (stack_excenv_t_node_t *) ee_s;
   excenv_t                *ee;

   ee = stack_excenv_t_top (ee_stack);
   if (ee == NULL)
   {
      fprintf (
            stderr,
            D_("invalid exception environment\n"));

      abort ();
   }

   return & (ee->env);
}

/**
 * \internal
 * \param   ee_s  the stack of exception environments for the actual
 *                thread.
 * \param   e     the exception to be thrown.
 * \pre     The root of the exception environments must be initialized
 *          either by exc_init() (if no threads are used) or by 
 *          threaded_exc_init() (if threads are used).
 *          There must be an actual exception environment into the stack
 *          of exception environments.
 * \return  Nothing
 * \post    A new exception is stored within the actual exception environment.
 *
 * \brief   The implementation of the THROW macro.
 *
 * This stores a new exception within the actual exception environment.
 */
void
exc_throw (void *ee_s, const exception_t *e)
{
   stack_excenv_t_node_t   *ee_stack = (stack_excenv_t_node_t *) ee_s;
   excenv_t *ee;

   bindtextdomain (PACKAGE, LOCALEDIR);

   /* get the actual excenv */
   ee = stack_excenv_t_top (ee_stack);
   if (ee == NULL)
   {
      char buf[1024];

      sprintf (
            buf,
            D_("any code that THROWs exeptions has to be\n"
               "%s within a TRY block\n"),
            "                         ");

      fprintf (
            stderr,
            "[Fatal(exception.c:200)]\n%s",
            buf);

      abort ();
   }

   queue_exception_t_enqueue (ee->e_queue, e);

   if (e->lvl == EXC_ERROR && e->was_catched == 0)
      longjmp (ee->env, 1);
}

/**
 * \internal
 * \param   ee_s  the stack of exception environments for the actual
 *                thread.
 * \pre     The root of the exception environments must be initialized
 *          either by exc_init() (if no threads are used) or by 
 *          threaded_exc_init() (if threads are used).
 *          There must be an actual exception environment into the stack
 *          of exception environments.
 * \return  The current exception environment.
 * \post    The current exception environment is removed from the stack, thus
 *          making the next one on the stack to the current exception
 *          environment.
 *
 * \brief   Get the current exception environment.
 *
 * The is the core of the CATCH() macro. It retrieves the actual exception
 * environment from the stack of exception environments and returns it. The
 * actual exception environment is removed from the stack.
 */
excenv_t *
excenv_catch (void *ee_s)
{
   stack_excenv_t_node_t   *ee_stack = (stack_excenv_t_node_t *) ee_s;
   excenv_t *ee;

   bindtextdomain (PACKAGE, LOCALEDIR);

   ee = stack_excenv_t_pop (ee_stack);
   if (ee == NULL)
   {
      char buf[1024];

      sprintf (
            buf,
            "[Fatal(exception.c:177)]\n%s",
            D_("use of CATCH with no previous TRY"));
      perror (buf);
      abort ();
   }

   return ee;
}

/**
 * \param   ee The exception environment to be checked.
 * \pre     \a ee must be a valid exception environment.
 * \return  Boolean wether \a ee has exceptions or not.
 * \retval  ==0   there are no exceptions
 * \retval  !=0   there are exceptions
 * \post    None
 *
 * \brief   Check for existent exceptions.
 *
 * This checks the given exception environment \a ee for existent
 * exceptions.
 */
int
excenv_has_exception (const excenv_t *ee)
{
   return ! list_exception_t_isempty (
         (list_exception_t_node_t *)ee->e_queue);
}

/**
 * \param   lvl   either ERROR or WARNING
 * \param   file  the file where the exception was created.
 * \param   line  the line in that file.
 * \param   errnum   an identifier of the exception. This might be
 *                   dublicated as it is normally just used as an
 *                   index for the error message. So rely only on this
 *                   if you check only a special kind of error.
 * \param   err_msg  a string describing what happens.
 * \pre     None
 * \return  The newly created exception.
 * \post    None
 *
 * \brief   Creates a new exception.
 *
 * This creates a new exception. Normally this function is called 
 * through the EXC() macro which fills in file and line automatically
 * by using __FILE__ and __LINE__ but sometimes it is desirable to
 * have direct control over those to values too. (For example with
 * the templates of list functions.)
 */
exception_t *
exc_new (
      const enum     exclvl_t lvl, 
      const char     *file,
      const int      line,
      const int      errnum, 
      const char     *err_msg)
{
   exception_t *e;

   bindtextdomain (PACKAGE, LOCALEDIR);

   e = (exception_t *) SCOT_MEM_GET (sizeof (exception_t));
   if (e == NULL)
      /* FIXME: make output to syslog or something... */
   {
      char buf[1024];

      sprintf (
            buf,
            "[Fatal(exception.c:220)]\n%s",
            D_("exc_new failed"));
      perror (buf);
      abort ();
   }

   /* This one time we write to lvl and id */
                           e->was_catched = 0;
   * (enum exclvl_t *) &   e->lvl         = lvl;
                           e->file        = file;
   * (int *) &             e->line        = line;
   * (int *) &             e->errnum      = errnum;
                           e->err_msg     = err_msg;

   return e;
}

/**
 * \param   ee The exception environment to be used.
 * \pre     \a ee must be a valid exception environment.
 * \return  The dequeued exception.
 * \post    The exception is removed from \a ee.
 *
 * \brief   Get the actual exception.
 *
 * This dequeues the the next exception from the exception environment and
 * returns it.
 */
exception_t *
retrive_exception (const excenv_t *ee)
{
   exception_t *e;

   e = queue_exception_t_dequeue (ee->e_queue);
   if (e != NULL)
      e->was_catched += 1;

   return e;
}

/**
 * \param   ee The exception environment to be used.
 * \pre     Must be in a CATCH Block. So the exception environment is already
 *          removed from the stack of exception environments and only 
 *          accessed by \a ee.
 * \return  Nothing
 * \post    All memory accessed over \a ee is freed, this includes all
 *          exceptions within it.
 *
 * \brief   Frees the actually catched exception environment.
 */
void free_catched (excenv_t *ee)
{
   free_excenv_t (ee);
}

/**
 * \param   e The exception to be used.
 * \pre     It is desirable to remove the exception first from the
 *          exception stack it is in, to keep from problems.
 * \return  Nothing
 * \post    All memory accessed over \a e is freed.
 *
 * \brief   Frees an exception.
 */
void
free_exception (exception_t *e)
{
   free_exception_t (e);
}

/**
 * \pre     None
 * \return  Nothing
 * \post    all memory allocated for any exception handling in the current
 *          thread is feed.
 *
 * \brief   Ends exception handling for the actual thread.
 *
 * This should be called before ending a thread to avoid memory leaks.
 */
void
exc_end (void)
{
   excenv_t *ee;

   list_exception_t_set_elem_free (free_exception_t);
   list_excenv_t_set_elem_free (free_excenv_t);

   if (tee_list == NULL)
   {
      stack_excenv_t_free (ee_stack);
   }
   else
   {
		thread_exc_end (SELF_THREAD);
   }

   list_exception_t_set_elem_free (NULL);
   list_excenv_t_set_elem_free (NULL);
}

void
thread_exc_end (THREAD_T t)
{
	list_thread_excenv_t_node_t   *tee_l;

   list_exception_t_set_elem_free (free_exception_t);
   list_excenv_t_set_elem_free (free_excenv_t);
	list_thread_excenv_t_set_elem_free (free_thread_excenv_t);

	tee_l = list_thread_excenv_t_find (tee_list, (thread_excenv_t *) &t);

	list_thread_excenv_t_delete (tee_l);

	/* 
	 * well, maybe this has to have some syncronization with
	 * threaded_exc_init or i make a function exc_fini, that
	 * does this final step and should only be called in the
	 * main thread.
	 */
	if (list_thread_excenv_t_isempty (tee_list))
		list_thread_excenv_t_free (tee_list);

	list_thread_excenv_t_set_elem_free (NULL);
   list_exception_t_set_elem_free (NULL);
   list_excenv_t_set_elem_free (NULL);
}

/**
 * \pre     \a e must be a valid exception.
 * \return  Nothing
 * \post    \a e is freed.
 *
 * \brief   Prints out the exception and frees it after that.
 */
void
print_exception (exception_t * e)
{
   fprintf (
         stderr, 
         "[%s(%s:%d)]\n(%d) %s\n",
         (e->lvl==EXC_ERROR)?D_("ERROR"):D_("WARNING"),
         e->file,
         e->line,
         e->errnum,
         e->err_msg);

	/* no more free at print...this is not intuitive usable. */
   /* free_exception (e); */
}

/**
 * \pre     \a ee must be a valid exception environment.
 * \return  Nothing
 * \post    \a ee is freed.
 *
 * \brief   Prints out all exceptions and frees them after that.
 *
 * This prints out all exception one by one using print_exception()
 * and after that frees also the exception environment \a ee.
 */
void
print_all_exceptions (excenv_t *ee)
{
   exception_t *e;

   e = retrive_exception (ee);
   while (e != NULL)
   {
      print_exception (e);
      e = retrive_exception (ee);
   }

   free_catched (ee);
}

/**
 * \param   ee the exception environment to be used.
 * \pre     \a ee must be a valid exception environment.\n
 *          There must be at least one exception environment left in the
 *          stack of exception environments.
 * \return  Nothing
 * \post    All exception within \a ee are in the actual exception environment.
 *
 * \brief   Forwards all exceptions in \a ee to the actual 
 *          exception environment.
 *
 * This did not free any exception but throw the from \a ee into the
 * actual exception environment.
 */
void
forward_all_exceptions (excenv_t *ee)
{
   exception_t *e;
   excenv_t    *_ee;

   if (tee_list != NULL)
      /* we use threads */
      _ee = threaded_exc_init ();
   else
      /* we don't use threads */
      _ee = exc_init ();

   e = retrive_exception (ee);
   while (e != NULL)
   {
      exc_throw (_ee, e);
      e = retrive_exception (ee);
   }

   free_catched (ee);
}

/**
 * \param   e  the exception to be checked.
 * \pre     \a e must be a valid exception.
 * \return  Boolean indicating if the exception was thrown within the
 *          actual exception environment or just be forwarded from another one.
 * \retval  ==0   the exception was forwarded.
 * \retval  !=0   the exception was thrown.
 * \post    None
 *
 * \brief   Checks wether \a e was thrown or forwarded.
 */
int
exc_in_this_try (exception_t *e)
{
   return e->was_catched == 1;
}


/************************************************************************
 * exception getter                                                     *
 ************************************************************************/
   enum exclvl_t
exc_lvl_get (exception_t *e)
{
   return e->lvl;
}

   int
exc_errnum_get (exception_t *e)
{
   return e->errnum;
}

   char *
exc_err_msg_get (exception_t *e)
{
   return (char *) e->err_msg;
}

   char *
exc_file_get (exception_t *e)
{
   return (char *) e->file;
}

   int
exc_line_get (exception_t *e)
{
   return e->line;
}