home *** CD-ROM | disk | FTP | other *** search
/ Oracle Video Server 3.0.3.1 / OVS_3031_NT.iso / win32 / medianet / server / include / yse.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-05-02  |  7.6 KB  |  193 lines
  1. /* Copyright (c) 1995 by Oracle Corporation.  All Rights Reserved.
  2.  *
  3.  * yse.h - OMX Exception Handling
  4.  *
  5.  * DESCRIPTION
  6.  * The exception handling mechanism provides the ability to throw and
  7.  * catch exceptional conditions.  The paradigm supported here is intended
  8.  * to be consistent with C++ behavior, in that some value (possibly
  9.  * structured) is thrown by one routine and caught by another routine
  10.  * with an established handler.
  11.  */
  12.  
  13. #ifndef YSE_ORACLE
  14. #define YSE_ORACLE
  15.  
  16. #ifndef SYSX_ORACLE
  17. #include <sysx.h>
  18. #endif
  19. #ifndef YS_ORACLE
  20. #include <ys.h>
  21. #endif
  22.  
  23. EXTC_START
  24.  
  25. /*
  26.  * Protected Regions
  27.  *
  28.  * SYNOPSIS
  29.  * yseTry                  yseTry
  30.  *   statement               statement
  31.  * { yseCatch[Obj]         yseFinally
  32.  *    statement }            statement
  33.  * [ yseCatchAll           yseEnd
  34.  *    statement ]
  35.  * yseEnd
  36.  *
  37.  * DESCRIPTION
  38.  * A protected region and associated handlers are bracketed by yseTry/yseEnd
  39.  * primitives.  Any exception that occurs within the TRY region may be caught
  40.  * by one of the associated CATCH handlers.  If no exception occurs when
  41.  * executing the TRY region, execution continues immediately following
  42.  * yseEnd.
  43.  *
  44.  * A CATCH handler may catch a specific exception or it may catch all
  45.  * exceptions.  A catch handler for a specific exception takes an exid
  46.  * argument, which must be a valid system identifier (see ysid.h).
  47.  * yseCatch(exid) will catch exid exceptions.  yseCatchObj(exid, exty, exobj)
  48.  * will also catch exid exceptions.  Additionally, it will declare a variable
  49.  * name exobj of type exty that is local to the handler.  The value of exobj
  50.  * will be initialized to the value of the object that was thrown with the
  51.  * exception.  If no object was thrown, the variable will remain
  52.  * uninitialized.  If the type exty differs from the type of the object
  53.  * thrown, the results are unpredictable.
  54.  *
  55.  * yseCatchAll will catch any exception, and if present, must be the last
  56.  * handler in the sequence.  Within yseCatchAll, the name yseExid may be
  57.  * used to refer to the caught exception, and yseExobj to refer to the
  58.  * exception object.
  59.  *
  60.  * If an exception is not caught by any CATCH handler, the exception is
  61.  * automatically rethrown to the next TRY block in the dynamic scope.  If
  62.  * an exception is not caught and there are no more possible handlers, the
  63.  * exception mechanism will panic.
  64.  *
  65.  * Within a catch handler, it is possible to rethrow the current exception
  66.  * (with associated object, if any) using yseRethrow.
  67.  *
  68.  * An alternative form of protected region uses a FINALLY section instead
  69.  * of CATCH handlers.  In this case, the statement bracketed by yseFinally
  70.  * and yseEnd will be executed whether or not an exception occurs in the
  71.  * TRY region.  If an exception did occur, control will immediately transfer
  72.  * to the FINALLY section.  Then, following the FINALLY section, the
  73.  * exception will automatically be rethrown.
  74.  *
  75.  * WARNINGS
  76.  * It is an error to leave a TRY, CATCH, or FINALLY region through any
  77.  * means other than a thrown exception or falling through the end.  Do
  78.  * not use return or goto within such a region.
  79.  *
  80.  * Local variables used within a protected region should be marked
  81.  * volatile to ensure that the variables contain a predictable value
  82.  * in the handler.
  83.  */
  84. #define yseTry \
  85.   { ysefr ysed; yseInf(&ysed); if (!syseSet(ysed.jb)) {
  86. #define yseEnd \
  87.   } yseTrf(&ysed); }
  88. #define yseCatch(exid) \
  89.   } else if (ysidEq((exid), ysed.id)) { ysed.rth = FALSE;
  90. #define yseCatchObj(exid, exty, exobj) \
  91.   } else if (ysidEq((exid), ysed.id)) { exty exobj; ysed.rth = FALSE; \
  92.     yseSetObj(&ysed, (dvoid *) &exobj, sizeof(exty));
  93. #define yseCatchAll \
  94.   } else { ysed.rth = FALSE;
  95. #define yseFinally \
  96.   } { ysed.liv = TRUE;
  97. #define yseRethrow yseRethrower(&ysed)
  98. #define yseExid    ysed.id
  99. #define yseExobj   ysed.obj
  100.  
  101. /*
  102.  * yseGetLoc - get location where exception was raised
  103.  *
  104.  * SYNOPSIS
  105.  * void yseGetLoc(CONST char **fn, sword *lineno);
  106.  *
  107.  * DESCRIPTION
  108.  * Within a CATCH handler, yseGetLoc() may be called to get the
  109.  * location in the program from which the exception was thrown.
  110.  * The location is specified in terms of filename and line number
  111.  * and is intended for debugging purposes only.
  112.  */
  113. #define yseGetLoc(f, l)  (*(f) = ysed.fn, *(l) = ysed.lineno)
  114.  
  115. /*
  116.  * yseThrow, yseThrowObj - throw an exception
  117.  *
  118.  * SYNOPSIS
  119.  * void yseThrow(CONST ysid *exid);
  120.  * void yseThrowObj(CONST ysid *exid, <l-value> obj);
  121.  *
  122.  * DESCRIPTION
  123.  * yseThrow() and yseThrowObj() throw an exception.  The exception
  124.  * may be caught by a dynamically scoped CATCH region.  yseThrowObj()
  125.  * may be used to throw a value along with the exception.  This value
  126.  * is copied and made available to a catch handler declared with
  127.  * yseCatchObj().  To understand exactly what this copying implies,
  128.  * throwing the value obj is exactly equivalent to the C statement
  129.  * "return obj" in all respects related to the way obj is treated, with
  130.  * the caveat that obj must be an l-value.
  131.  */
  132. #define yseThrow(exid)          \
  133.   yseThrower((exid), (dvoid *) 0, (size_t) 0, __FILE__, __LINE__)
  134. #define yseThrowObj(exid, obj)  \
  135.   yseThrower((exid), (dvoid *) &(obj), sizeof(obj), __FILE__, __LINE__)
  136.  
  137. /*
  138.  * ysepf, ysePanic, yseSetPanic - Panic Functions
  139.  *
  140.  * DESCRIPTION
  141.  * When a catastrophic failure occurs, and the current thread of execution
  142.  * is not recoverable, a routine may panic, thus causing a sort of software
  143.  * trap, by calling ysePanic().  The exception that is causing the death
  144.  * should be passed to the routine.  By default, a panic will cause the
  145.  * process to abort, possibly with some additional system information
  146.  * recorded for analysis.  However, this may be overridden by installing
  147.  * a user-defined panic routine using yseSetPanic().  yseSetPanic() will
  148.  * install pfunc as the panic routine.  It will return the previously
  149.  * installed panic routine if was one or a null pointer otherwise.  The
  150.  * ptr value will be passed to the panic routine when it is invoked.
  151.  *
  152.  * A user-defined panic routine should generally perform application-
  153.  * specific cleanup.  The routine may exit either by throwing an exception
  154.  * or return.  The former style is recommended since it allows handlers to
  155.  * perform cleanup in a consistent fashion.  If the routine simply returns,
  156.  * then the default process abort action will be taken.
  157.  */
  158. typedef void (*ysepf)(CONST ysid *exid, dvoid *ptr);
  159. void  ysePanic(CONST ysid *exid);
  160. ysepf yseSetPanic(ysepf pfunc, dvoid *ptr);
  161.  
  162. /*
  163.  * PRIVATE DECLARATIONS
  164.  */
  165. typedef struct ysefr ysefr;                               /* exception frame */
  166.  
  167. void yseInf(ysefr *fr);
  168. void yseTrf(ysefr *fr);
  169. void yseThrower(CONST ysid *exid, dvoid *obj, size_t objsz,
  170.         CONST char *fn, sword lineno);
  171. void yseRethrower(ysefr *fr);
  172. void yseSetObj(ysefr *fr, dvoid *obj, size_t objsz);
  173. #define yseTrigger(evt)  \
  174.   ysTrigger(evt, ysed.id, ysed.obj, ysmGetSize(ysed.obj))
  175.  
  176.  
  177. /* DISABLE check_naming */
  178. struct ysefr
  179. {
  180.   ysefr      *prev;                                        /* previous frame */
  181.   sysejb      jb;                                             /* jump buffer */
  182.   CONST ysid *id;                                    /* exception identifier */
  183.   dvoid      *obj;                                     /* exception argument */
  184.   boolean     rth;                   /* true if exception should be rethrown */
  185.   boolean     liv;             /* true if an exception occurred in the frame */
  186.   CONST char *fn;                                     /* filename of thrower */
  187.   sword       lineno;                              /* line number of thrower */
  188. };
  189. /* ENABLE check_naming */
  190.  
  191. EXTC_END
  192. #endif /* YSE_ORACLE */
  193.