home *** CD-ROM | disk | FTP | other *** search
/ Oracle Video Server 3.0.3.1 / OVS_3031_NT.iso / win32 / medianet / server / include / yocoa.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-11-21  |  17.7 KB  |  421 lines
  1. /* Copyright (c) 1995 by Oracle Corporation.  All Rights Reserved.
  2.  *
  3.  * yocoa.h - Oracle OMX Common Object Adapter
  4.  *
  5.  * DESCRIPTION
  6.  * The following routines should be used only by programs which implement
  7.  * objects, also known as servers.  Of course, any program may act as a
  8.  * server.
  9.  */
  10.  
  11. #ifndef YOCOA_ORACLE
  12. #define YOCOA_ORACLE
  13.  
  14. #ifndef SYSX_ORACLE
  15. #include <sysx.h>
  16. #endif
  17. #ifndef YO_ORACLE
  18. #include <yo.h>
  19. #endif
  20. #ifndef MN_ORACLE
  21. #include <mn.h>
  22. #endif
  23.  
  24. EXTC_START
  25.  
  26. /* Exceptions */
  27. externref ysidDecl(YO_EX_DUPLICATE);            /* duplicate entry exception */
  28. externref ysidDecl(YO_EX_STATELESS);    /* specified interface was stateless */
  29.  
  30. /*
  31.  * yoload - object loader
  32.  *
  33.  * DESCRIPTION
  34.  * An object loader is used by the object layer to activate or deactivate
  35.  * an object.  When an object is being activated, the loader routine for
  36.  * the object's implementation is invoked and passed the object reference.
  37.  * At this time, any state associated with the object may be loaded into
  38.  * memory as the system will guarantee that all subsequent operations on
  39.  * the same object will be routed to the same process until the object is
  40.  * deactivated.  The loader has available to it the reference data in order
  41.  * to determine what to load.  Object activiation is indicated when the
  42.  * activate parameter is TRUE.  If the load fails, FALSE should be returned
  43.  * from the loader; otherwise, TRUE should be returned to indicate success.
  44.  *
  45.  * Any implementation that includes a loader implicitly supports object
  46.  * deactivation and the system may attempt to deactivate the object at
  47.  * various times, including explicit object deactivation and process
  48.  * termination.  The system guarantees that it will call the loader on
  49.  * all activate objects during process termination.  The deactivation
  50.  * may not be refused.  Object deactivation is indicated when the
  51.  * activate parameter is FALSE.
  52.  */
  53. typedef boolean (*yoload)(dvoid *ref, boolean activate);    /* object loader */
  54.  
  55. /*
  56.  * yoSetImpl - set an implementation
  57.  *
  58.  * DESCRIPTION
  59.  * yoSetImpl() binds an interface to its implementation.  The interface
  60.  * is identified by its tag generated by the IDL compiler with the name
  61.  * <interface>__id.  The implementation is identified by any tag that
  62.  * uniquely identifies the implementation, although it should normally
  63.  * be one that is registered in the implementation repository.  If no
  64.  * implementation id is specified, the program name is used (taken from
  65.  * ysProgName()).
  66.  *
  67.  * An implementation consists of a set of stubs, an implementation
  68.  * dispatch vector, an object adapter, and optionally, a object loader.
  69.  * The elements are explained as follows:
  70.  *
  71.  * stubs is a null-terminated array of server-side stub routines that
  72.  * will be invoked when a request arrives.  These are the skeletons
  73.  * that perform the unmarshalling of the request, make the upcall,
  74.  * and then marshal the results.  The server-side stub routines are
  75.  * generated by the IDL compiler which also generates an array
  76.  * named <interface>__stubs for use here.  Note that the stubs are
  77.  * specific to the interface, not the implementation, and
  78.  * so the same set of stubs may be used for several different
  79.  * implementations to the same interface.
  80.  *
  81.  * The impldef is a structure whose fields point to the actual routines
  82.  * that implement the operations.  The type of the structure is generated
  83.  * by the IDL Compiler as is a default initialization for the structure.
  84.  * This may be modified as necessary to bind different routines to the
  85.  * operation names.  The name of the structure generated is
  86.  * <interface>__impl.
  87.  *
  88.  * loader is the name of the loader function that is to be used during
  89.  * object activation and deactivation of persistent objects.  If no
  90.  * loader is provided, then objects for this implementation must be
  91.  * created during execution and cannot live longer than the process itself.
  92.  *
  93.  * state is a pointer to some optional state information which may be
  94.  * associated with a particular implementation.
  95.  *
  96.  * stateless is a boolean which indicates if the implementation is stateless.
  97.  * If an implementation is stateless, the ORBD will be notified of the
  98.  * existance of the implemenation.  Calling yoGetState() or yoSetState()
  99.  * with a stateless object reference will result in the exception
  100.  * YO_EX_STATELESS.
  101.  */
  102. typedef struct  yostub yostub;                            /* stub descriptor */
  103. typedef struct  yostbb yostbb;
  104. typedef struct  yooad  yooad;                   /* object adapter descriptor */
  105.  
  106. /* DISABLE check_naming */
  107. struct yostbb
  108. {
  109.   CONST char *opernm;                                      /* operation name */
  110.   yopar *parms;                                     /* parameter description */
  111.   void (*oper)(dvoid *ref, yoenv *ev, dvoid *impldef, dvoid **args); /* oper */
  112. };
  113.  
  114. struct yostub
  115. {
  116.   yowiden widen;
  117.   const char* const* bases;
  118.   yostbb stuba[1];
  119. };
  120. /* ENABLE check_naming */
  121.  
  122. void yoSetImpl(CONST ysid *intf, CONST char *impl, yostub *stubs,
  123.                CONST dvoid *impldef, yoload loader, boolean stateless,
  124.            dvoid *state);
  125.  
  126. /*
  127.  * yoCreate - create an object
  128.  *
  129.  * DESCRIPTION
  130.  * yoCreate() creates an object.  intf and impl together must define an
  131.  * implementation previously specified with yoSetImpl().  An object
  132.  * reference to the created object is returned.
  133.  *
  134.  * id is a pointer to reference data whose type is sequence<octet>.
  135.  * The id is immutable identification information, chosen by the
  136.  * implementation at object creation time and never changed.  The
  137.  * usage of the id is entirely implementation-defined.  Two objects
  138.  * created with the same id are not the same object as far as the
  139.  * object layer is concerned.  For implementations with loaders,
  140.  * the reference data is made available to the loader to allow
  141.  * the object to be reactivated.  In other words, it persists past
  142.  * the activation (unlike the state).  The id may be null.  If id is
  143.  * non-null, the value is copied into the reference returned.
  144.  *
  145.  * state is a pointer to in-memory state that may be used while
  146.  * the object is active.  This is a convenience for fast access to
  147.  * in-memory information.  For object without loaders, it is usually
  148.  * the primary means to access the state of the object.
  149.  *
  150.  * A created object starts off as an active object.
  151.  */
  152. dvoid *yoCreate(CONST ysid *intf, CONST char *impl, yoRefData *id,
  153.                 CONST char *ignored, dvoid *state);
  154.  
  155. /*
  156.  * yoDispose - destroy an object
  157.  *
  158.  * DESCRIPTION
  159.  * yoDispose() destroys an object.  This may be used even if there are
  160.  * still outstanding references to the object.  These references will
  161.  * no longer be valid.  The object is not deactivated before it is
  162.  * disposed and the object's loader (if any) will not be called.
  163.  */
  164. void yoDispose(dvoid *ref);
  165.  
  166. /*
  167.  * yoGetId, yoFreeId - reference data
  168.  *
  169.  * DESCRIPTION
  170.  * yoGetId() returns a copy of the reference data (if any) is returned for
  171.  * the given object reference.  The pointer which is returned should be
  172.  * freed using yoFreeId().
  173.  */
  174. yoRefData *yoGetId(CONST dvoid *ref);
  175. void yoFreeId(yoRefData *id);
  176.  
  177. /*
  178.  * yoGetState, yoSetState - set & get the in-memory state
  179.  *
  180.  * DESCRIPTION
  181.  * Associated with each activated object is some in-memory state.
  182.  * These routines allow a pointer to this state to be retrieved
  183.  * from and set into the object reference.
  184.  */
  185. dvoid *yoGetState(CONST dvoid *ref);
  186. void yoSetState(CONST dvoid *ref, CONST dvoid *state);
  187.  
  188. /*
  189.  * yoGetImplState - get the implementation state
  190.  *
  191.  * DESCRIPTION
  192.  * This routine allows the implementation state information to be retrieved
  193.  * from the object reference.
  194.  */
  195. dvoid *yoGetImplState(CONST dvoid *ref);
  196.  
  197. /*
  198.  * yoGetCaller - return an object reference to the caller
  199.  *
  200.  * DESCRIPTION
  201.  * This function returns an opaque object reference which identifies the
  202.  * entity which made the current server call.  This object reference can
  203.  * be passed to yoWatchOwner() to detect client death.
  204.  */
  205. dvoid *yoGetCaller(void);
  206.  
  207. /*
  208.  * yoQueCreate, yoQueDestroy - create & destroy ysque's for YO
  209.  *
  210.  * DESCRIPTION
  211.  * yoQueCreate() creates a queue for use by several functions defined
  212.  * in this interface file, yoService(), yoShutdown(), yoImplReady(),
  213.  * and yoObjListen().  The forementioned functions require that the ysque
  214.  * passed in was created by yoQueCreate().  The ysque returned is also vaild
  215.  * for use with any of the functions defined in ysv.h which require ysque's.
  216.  *
  217.  * yoQueDestroy() destroys a queue created via yoQueCreate().
  218.  */
  219. ysque *yoQueCreate(CONST char *name);
  220. void yoQueDestroy(ysque *q);
  221.  
  222. /*
  223.  * yoService, yoThreadService, yoShutdown - begin & end service
  224.  *
  225.  * DESCRIPTION
  226.  * yoService() and yoThreadService() begin servicing incoming
  227.  * implementation/object requests for the specified queue.  If a null queue
  228.  * is specified, the default queue is serviced. As requests come in,
  229.  * they are dispatched to the appropriate methods to implement the requests.
  230.  * yoService() and yoThreadService() block until yoShutdown() is called.
  231.  *
  232.  * yoService() runs completely in the current thread, and is appropriate use
  233.  * in non-threaded programs.
  234.  *
  235.  * yoThreadService() services the queue with multiple threads, the arguments
  236.  * specifying semantics and limits.  On entry, mint threads will be started,
  237.  * each servicing the queue.  Only maxt will ever be allowed to exist.  If
  238.  * maxt is set, deadlocks may occur if all threads are busy waiting for the
  239.  * processing of requests that can't be serviced because there are no
  240.  * threads available.  As each request is about to be serviced, if no more
  241.  * threads are available, and maxt threads don't yet exist, a new thread is
  242.  * started.  This will guarantee an available thread at all times (up to
  243.  * maxt).  As each service completes, each thread sees if keept is exceeded.
  244.  * If so, then that thread exits.  A call with mint = 0 and keept = 0 gives
  245.  * "thread-per-request" semantics.  Calling with mint = X, keept = X, maxt = X
  246.  * gives bounded thread-pool semantics with X threads.
  247.  *
  248.  * yoShutdown() is used to terminate service started with yoService() or
  249.  * yoThreadService(). All unprocessed requests are rejected and no new ones
  250.  * will be accepted.  Active threads are allowed to run to completion.
  251.  * Finally, yoService() will return.  yoService() will also return if there
  252.  * are no active implementations or objects.
  253.  *
  254.  * The queue passed to yoService(), yoThreadService() and yoShutdown() must
  255.  * be created using yoQueCreate().
  256.  */
  257. void yoService(ysque *q);
  258. void yoThreadService(ysque *q, sword mint, sword keept, sword maxt);
  259. void yoShutdown(ysque *q);
  260.  
  261. /*
  262.  * yoDefQue - get the default queue
  263.  *
  264.  * DESCRIPTION
  265.  * yoDefQue() returns the default queue.  This is the actual queue that
  266.  * is used when a null queue is passed to yoService(), yoShutdown(),
  267.  * yoImplReady(), etc.
  268.  */
  269. ysque *yoDefQue(void);
  270.  
  271. /*
  272.  * yoImplReady, yoImplDeactive - implementation activation & deactivation
  273.  * yoImplSuspend, yoImplResume - suspend & resume implementation
  274.  *
  275.  * DESCRIPTION
  276.  * yoImplReady() informs the object layer that the server is ready to
  277.  * accept requests for objects based on the given implementation.  No
  278.  * requests can be received or processed by an implementation until this
  279.  * routine has been called.
  280.  * yoImplReady() may be passed a queue onto which dispatch events are
  281.  * posted that will actually cause method invocation to take place when 
  282.  * dequeued.  If no queue is specified, requests are are placed in the default
  283.  * queue which can be serviced by calling yoService with a null queue.
  284.  * Invocations of the loader are also posted to the same queue.  The queue
  285.  * passed to yoImplReady() must have been created by yoQueCreate().
  286.  *
  287.  * yoImplDeactivate() informs the object layer that the server is no
  288.  * longer able to accept requests for objects based on the given
  289.  * implementation.  All active objects of the given type are deactivated
  290.  * and the ORB is not permitted to forward any more calls.  Any pending
  291.  * but unprocessed requests are rejected.
  292.  *
  293.  * yoImplSuspend() suspends the acceptance of operations for the objects
  294.  * of the given implementation.  Any calls forwarded to the server
  295.  * while this operation is suspended are rejected.
  296.  *
  297.  * yoImplResume() resumes the acceptance of operations for objects of
  298.  * the given implementation.
  299.  */
  300. void yoImplReady(CONST ysid *intf, CONST char *impl, ysque *q);
  301. void yoImplDeactivate(CONST ysid *intf, CONST char *impl);
  302. void yoImplSuspend(CONST ysid *intf, CONST char *impl);
  303. void yoImplResume(CONST ysid *intf, CONST char *impl);
  304.  
  305. /*
  306.  * yoObjListen, yoObjDeactivate - object activation & deactivation
  307.  *
  308.  * DESCRIPTION
  309.  * An object is considered active once the loader for the object
  310.  * completes or after yoCreate() completes.  Once the object is
  311.  * active, it may have method calls dispatched on it.  yoObjListen()
  312.  * allows a queue to be associated with the reference where all
  313.  * invocations are queued for dispatch.  A null queue explicitly
  314.  * causes the invocations to be dispatched on thread yields.  By
  315.  * default, the queue used for dispatch is the same as that given
  316.  * to yoImplReady().  If yoImplReady() was never called for the
  317.  * object's implementation, then the default is a null queue.  The
  318.  * queue passed to yoObjListen() must have been created by yoQueCreate().
  319.  *
  320.  * yoObjDeactivate() is used to explicitly deactivate an object.
  321.  * As long as an object is active, all operations invoked on the
  322.  * object are routed to the same server process.  Once the object
  323.  * is deactivated, it may be reactivated in another server process
  324.  * (depending on the characteristics of the object).  For an object
  325.  * with no loader, yoObjDeactivate() is equivalent to yoDispose().
  326.  */
  327. void yoObjListen(CONST dvoid *ref, ysque *q);
  328. void yoObjDeactivate(dvoid *ref);
  329.  
  330.  
  331. /*
  332.  * yodsSetImpl, yodsParams, yodsReturn, yodsException - Dynamic Skeleton
  333.  *
  334.  * DESCRIPTION
  335.  * yodsSetImpl() sets up a DSI implementation taking arguments similar to
  336.  * yoSetImpl().  The impfunc is the DSI dynamic implementation function.
  337.  * This dynamic implementation function is responsible for decoding the
  338.  * requests paramenters using yodsParams() and returning a result via
  339.  * yodsReturn().  Exceptions are returned using either yseThrow() or
  340.  * yodsException().
  341.  *
  342.  */
  343. typedef struct yosreq yosreq;
  344. typedef void (*yodir)(CONST dvoid *ref, yoenv *ev, CONST char *opernm,
  345.               yosreq *req);
  346.  
  347. void yodsSetImpl(CONST ysid *intf, CONST char *impl, CONST yodir impfunc,
  348.                  yoload loader, boolean stateless, dvoid *state);
  349. dvoid **yodsParams(yosreq *req, yopar *parms);
  350. void yodsReturn(yosreq *req, dvoid *value, size_t size);
  351. void yodsException(yosreq *req, CONST ysid *exid, dvoid *obj, size_t size);
  352.  
  353.  
  354. /*
  355.  * yodsReSendReq, yodsFreeRep, yodsProxyRep - resend a request received via DSI
  356.  *
  357.  * DESCRIPTION
  358.  * yodsReSendReq() resends the request to the specified object.
  359.  * yodsReSendReq() must be called from within a dynamic implementation
  360.  * function. yodsReSendReq() can *not* be called after calling yodsParams().
  361.  * The event will be triggered with a pointer to a yodsrep.  This is a handle
  362.  * to the reply data.  This handle should be freed using yodsFreeReply().
  363.  * yodsProxyRep() can be used to pass the reply from yodsReSendReq() to
  364.  * the client which invoked the dynamic implementation function.
  365.  */
  366. typedef struct yodsrep yodsrep;
  367.  
  368. void yodsReSendReq(yosreq *req, CONST dvoid *ref, yoenv *ev, ysevt *evt);
  369. void yodsFreeRep(yodsrep *rep);
  370. void yodsProxyRep(yosreq *req, yodsrep *rep);
  371.  
  372. /*
  373.  * yoimpadm - implementation administrative callback function
  374.  *
  375.  * DESCRIPTION
  376.  * yoimpadm is called whenever the administrative state of an implementation
  377.  * changes.  The implementation is identified by the parameters intf and impl.
  378.  * The stateless parameter is the boolean passed to yoSetImpl.  ostate is the
  379.  * original administrative state.  nstate is the new administrative state.
  380.  * Based on the values of ostate and nstate the callback should do whatever
  381.  * is appropriate/possible to make the requested change in state.  usrp is
  382.  * the user specified pointer passed to yoSetImplAdmCb() when setting the
  383.  * callback for a particular implementation.
  384.  *
  385.  */
  386.  
  387. #define YOIMPADST_DOWN          0            /* go down as soon as practical */
  388. #define YOIMPADST_RUN           1           /* resume from halt or congested */
  389. #define YOIMPADST_HALTED        2    /* suspend but allow set of admin state */
  390. #define YOIMPADST_CONGESTED     3                 /* pretend to be congested */
  391. #define YOIMPADST_RESTART       4      /* restart from beginning if possible */
  392. #define YOIMPADST_QUIESCE       5      /* process current load, take no more,
  393.                                           go down gracefully */
  394.  
  395. typedef void (*yoimpadm)(CONST ysid *intf, CONST ysid *impl, boolean stateless,
  396.                          ub4 ostate, ub4 nstate, dvoid *usrp);
  397. /*
  398.  * yoSetImplAdmCb - set implementation administrative callback.
  399.  *
  400.  * DESCRIPTION
  401.  * Sets the administrative callback for a particular implementation.  If
  402.  * yoSetImplAdmCb() is not called for an implementation or called with
  403.  * a null admcb, the default administrative callback is used.
  404.  *
  405.  *The default administrative callback will do the following:
  406.  *
  407.  *      nstate                  Action
  408.  *      YOIMPADST_DOWN          yoImplDeactivate(intf,impl);
  409.  *      YOIMPADST_RUN           yoImplResume(intf,impl);
  410.  *      YOIMPADST_HALTED        <none>
  411.  *      YOIMPADST_CONGESTED     yoImplSuspend(intf,impl);
  412.  *      YOIMPADST_RESTART       <none>
  413.  *      YOIMPADST_QUIESCE       if(stateless) yoImplDeactivate(intf,impl);
  414.  */
  415. void yoSetImplAdmCb(CONST ysid *intf, CONST ysid *impl, yoimpadm admcb,
  416.                     dvoid *usrp);
  417.  
  418. EXTC_END
  419.  
  420. #endif /* YOCOA_ORACLE */
  421.