home *** CD-ROM | disk | FTP | other *** search
/ Oracle Video Server 3.0.3.1 / OVS_3031_NT.iso / win32 / medianet / server / include / ys.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-01-28  |  8.9 KB  |  228 lines
  1. /* Copyright (c) 1995, 1996 by Oracle Corporation.  All Rights Reserved.
  2.  *
  3.  * ys.h - OMN System Layer
  4.  *
  5.  * DECSRIPTION
  6.  * The Oracle Media Net System Layer (also known as the ys layer)
  7.  * consists of a number of fundamental packages and library routines
  8.  * that together comprise a small, portable virtual operating system
  9.  * and user library.  It is not intended to replace the standard C
  10.  * library, nor does it actually implement a virtual operating system.
  11.  * Instead, it provides a portable interface to O/S functions, and a
  12.  * standard library of functions that can be relied upon to present
  13.  * in every program incorporating this system layer.
  14.  *
  15.  * THREAD SAFETY
  16.  * The system layer is designed to be completely thread-safe.  In order
  17.  * to use the system layer in a multi-threaded environment, you must
  18.  * initialize the threads package before creating your first thread.
  19.  * See the "THREAD SAFETY" section at the top of each OMN System Layer
  20.  * header file for more information specific to the interface defined
  21.  * there.
  22.  *
  23.  * EXCEPTIONS
  24.  * The system layer provides an exception mechanism designed to emulate
  25.  * the C++ exception model.  However, the usage of a non-standard exception
  26.  * mechanism is troublesome, especially across public interfaces that are
  27.  * used in a wide variety of conditions.  Therefore, the system layer itself
  28.  * only throws two classes of exceptions:
  29.  *
  30.  *   + those that indicate a programming error (such as a bad parameter)
  31.  *   + those that indicate a near-fatal condition (such as out of memory)
  32.  *
  33.  * It is rarely possible to recover from these exceptions in any meaningful
  34.  * way other than to simply terminate the running thread or program.  Other
  35.  * sorts of errors that are detectable and recoverable are indicated through
  36.  * status codes returned from a function call.  This design allows the System
  37.  * Layer to be used essentially unencumbered by its exception model.  In the
  38.  * case that an exception does arise, the default behavior is to terminate
  39.  * the program.  See yse.h for more information about the exception model.
  40.  */
  41.  
  42. #ifndef YS_ORACLE
  43. #define YS_ORACLE
  44.  
  45. #ifndef SYSX_ORACLE
  46. #include <sysx.h>
  47. #endif
  48. #ifndef YSID_ORACLE
  49. #include <ysid.h>
  50. #endif
  51.  
  52. EXTC_START
  53.  
  54. /*
  55.  * Type Declarations
  56.  */
  57. typedef struct ysbv ysbv;                                   /* buffer vector */
  58. typedef struct yslst yslst;                                /* list structure */
  59. typedef struct ysle ysle;                                    /* list element */
  60. typedef struct yslmtc yslmtc;                      /* get metrics for a list */
  61. typedef struct ysfop ysfop;                  /* fixed-object pool descriptor */
  62. typedef struct ysmhp ysmhp;                               /* heap descriptor */
  63. typedef struct ysque ysque;                              /* queue descriptor */
  64. typedef struct ysevt ysevt;                              /* event descriptor */
  65.  
  66. typedef dvoid *(*ysmaf)(size_t len);                  /* allocation function */
  67. typedef dvoid *(*ysmrf)(dvoid *ptr, size_t len);    /* reallocation function */
  68. typedef void   (*ysmff)(dvoid *ptr);                /* deallocation function */
  69.  
  70. /*
  71.  * ysInit, ysTerm - initialization & termination
  72.  *
  73.  * DESCRIPTION
  74.  * ysInit() must be called before using any other routine in the ys layer,
  75.  * or any software that depends on the OMN system layer.  osdp is a pointer
  76.  * to memory reserved for operating-system dependent functionality.  This
  77.  * memory must be allocated by the caller to last for the lifetime of the
  78.  * program (usually on the stack somewhere near main()).  It should be
  79.  * declared as a ub1 array of SYSX_OSDPTR_SIZE bytes.  nm is the name of
  80.  * the program being run.  This is used when reporting diagnostics, when
  81.  * printing a usage description, and also to generate a name for the
  82.  * process in distributed environments.  By convention, it is usually the
  83.  * name of the executable.
  84.  *
  85.  * ysTerm() must be called just prior to program termination to ensure that
  86.  * all resources used by the ys layer are returned to the operation system.
  87.  *
  88.  * The ysInit()/ysTerm() pair may be called more than once in any given 
  89.  * process.  However, they must not called from within more than one
  90.  * concurrently executing thread at the same time.  Additional calls to 
  91.  * ysInit() will increment a reference count and return silently leaving 
  92.  * the previous initialization intact.  Subsequent calls to ysTerm() will
  93.  * decrement the refcnt.  YS resources are freed only when the reference 
  94.  * count drops to zero.
  95.  */
  96. void ysInit(dvoid *osdp, CONST char *nm);
  97. void ysTerm(dvoid *osdp);
  98.  
  99. /*
  100.  * ysVersion - get version of OMN
  101.  *
  102.  * DESCRIPTION
  103.  * ysVersion() writes a string describing the current version of OMN to
  104.  * buf.  A maximum of len bytes will be written.  A sufficient maximum
  105.  * length is 80.  As a convenience, it returns the pointer to buf that
  106.  * was passed in.
  107.  */
  108. char *ysVersion(char *buf, size_t len);
  109.  
  110. /*
  111.  * ysProgName, ysGetOsdPtr, ysGetHostName, ysGetPid, ysGetAffinity,
  112.  *    ysGetCpuTime, ysGetUpTime, ysGetMemUsage - get program information
  113.  *
  114.  * SYNOPSIS
  115.  * const char *ysProgName(void);
  116.  * dvoid *ysGetOsdPtr(void); 
  117.  * const char *ysGetHostName(void);
  118.  * const char *ysGetPid(void);
  119.  * const char *ysGetAffinity(void);
  120.  * void ysGetCpuTime(sysb8 *cputm);
  121.  * void ysGetUpTime(sysb8 *uptm);
  122.  * ub4 ysGetMemUsage(void);
  123.  *
  124.  * DESCRIPTION
  125.  * These routines return various information about the current process:
  126.  *
  127.  * ysProgName() returns the program name passed to ysInit().  ysGetOsdPtr()
  128.  * returns the OSD pointer passed to ysInit().
  129.  *
  130.  * ysGetHostName() returns the host name for the system, as determined
  131.  * by the operating system.  If no host name is defined, the routine will
  132.  * return a null pointer.
  133.  *
  134.  * ysGetPid() returns the proccess ID of the current process, as determined
  135.  * by the operating system.  If the operating system has no notion of process
  136.  * identifier, the routine will return a null pointer.  ysGetAffinity()
  137.  * returns the affinity of the current process to a particular processor,
  138.  * as determined by the operating system.  If the operating system has no
  139.  * notion of affinity, the routine will return a null pointer.
  140.  *
  141.  * ysGetCpuTime() returns the amount of CPU time used by the process, as
  142.  * determined by the operating system.  This is returned in units of
  143.  * microseconds.  ysGetUpTime() returns the elapsed time since ysInit()
  144.  * was called.  This is returned in units of microseconds.  ysGetMemUsage()
  145.  * returns the amount of memory currently being consumed by the process,
  146.  * as determined by the operating system.  This is returned in units of
  147.  * kilobytes.
  148.  */
  149. CONST char *ysProgName(void);
  150. dvoid *ysGetOsdPtr(void);
  151.  
  152. #define ysGetHostName()  ((CONST char *) ysResGetLast("ys.hostname"))
  153. #define ysGetPid()       ((CONST char *) ysResGetLast("ys.pid"))
  154. #define ysGetAffinity()  ((CONST char *) ysResGetLast("ys.affinity"))
  155.  
  156. void ysGetCpuTime(sysb8 *cputm);
  157. void ysGetUpTime(sysb8 *uptm);
  158. ub4  ysGetMemUsage(void);
  159.  
  160. /*
  161.  * ysFmtVersion - format a version string in a conventional format
  162.  *
  163.  * DESCRIPTION
  164.  * ysFmtVersion() is used by products to consistently format a one-line
  165.  * description of the product, its version and release status, and its
  166.  * build date. The description is written to buf. As a convenience, the 
  167.  * pointer to buf is returned by the function. If you do not want a build
  168.  * date to be included, pass in null for the date. The release status
  169.  * may be one of the following:
  170.  */
  171. #define YSLVL_NONE   0                                          /* no status */
  172. #define YSLVL_DEVEL  1                                        /* Development */
  173. #define YSLVL_DEVRL  2                                /* Developer's Release */
  174. #define YSLVL_ALPHA  3                                              /* Alpha */
  175. #define YSLVL_BETA   4                                               /* Beta */
  176. #define YSLVL_LIMIT  5                                 /* Limited Production */
  177. #define YSLVL_PROD   6                                         /* Production */
  178.  
  179. char *ysFmtVersion(char *buf, size_t buflen, CONST char *prodnm,
  180.            CONST char *vrs, sword sts, CONST char *date);
  181.  
  182. /* include other public, external headers as a convenience */
  183. #ifndef YSBV_ORACLE
  184. #include <ysbv.h>
  185. #endif
  186. #ifndef YSFO_ORACLE
  187. #include <ysfo.h>
  188. #endif
  189. #ifndef YSSTR_ORACLE
  190. #include <ysstr.h>
  191. #endif
  192. #ifndef YSLST_ORACLE
  193. #include <yslst.h>
  194. #endif
  195. #ifndef YSHSH_ORACLE
  196. #include <yshsh.h>
  197. #endif
  198. #ifndef YSC_ORACLE
  199. #include <ysc.h>
  200. #endif
  201. #ifndef YSE_ORACLE
  202. #include <yse.h>
  203. #endif
  204. #ifndef YSTM_ORACLE
  205. #include <ystm.h>
  206. #endif
  207. #ifndef YSV_ORACLE
  208. #include <ysv.h>
  209. #endif
  210. #ifndef YSMSC_ORACLE
  211. #include <ysmsc.h>
  212. #endif
  213. #ifndef YSL_ORACLE
  214. #include <ysl.h>
  215. #endif
  216. #ifndef YSR_ORACLE
  217. #include <ysr.h>
  218. #endif
  219. #ifndef YSLOG_ORACLE
  220. #include <yslog.h>
  221. #endif
  222. #ifndef YSTHR_ORACLE
  223. #include <ysthr.h>
  224. #endif
  225.  
  226. EXTC_END
  227. #endif /* YS_ORACLE */
  228.