/*--------------------------------------------------------------------
 * Name:   mscpm.h
 * Author: ITEX C-Code Generator
 *
 * Copyright 1999 Telelogic AB, All rights reserved.
 *
 * This Program is owned by Telelogic and is protected by national
 * copyright laws and international copyright treaties. Telelogic
 * grants you the right to use this Program on one computer or in one
 * local computer network at any one time.  Under this License you may
 * only modify the source code for the purpose of adapting it to your
 * environment. You must reproduce and include any copyright and
 * trademark notices on all copies of the source code.  You may not
 * use, copy, merge, modify or transfer the Program except as provided
 * in this License.  Telelogic does not warrant that the Program will
 * meet your requirements or that the operation of the Program will be
 * uninterrupted and error free. You are solely responsible that the
 * selection of the Program and the modification of the source code
 * will achieve your intended results and that the results are
 * actually obtained.
 */

#ifndef MSCPM_H
#define MSCPM_H

/*--------------------------------------------------------------------
 *
 *  Notice:
 *
 *  This code defines an internal interface for the ITEX Code
 *  Generator runtime environment, in particular for MSC generation
 *  using the Telelogic MSC Editor (MSCE). Any attempt to use this
 *  code for any other purpose is not supported by Telelogic.
 *
 *  Background:
 *
 *  Since the Tau postmaster interface is not multi-thread-safe, and
 *  in some versions will fail when called from multiple threads, this
 *  header file defines some wrappers for the postmaster calls that
 *  guarantees that only one thread is responsible for communication
 *  with the postmaster.
 *
 *  General Comments:
 *
 *  The interface ensures that no more than one RPC is active at
 *  one time.
 *
 *  The code internals assumes that a file mscthread.h is defined where
 *  some platform-independent macrose define threading and semaphore
 *  related calls.
 *
 *  The internal code creates a MscPmDispatcherThread that runs all
 *  the communication with postmaster. The presense of this extra
 *  thread may introduce constraints on other code, in particular the
 *  code for concurrent TTCN introduced in the 'concurrent.sunos5'
 *  example folder in ITEX 3.2 - 3.5 installations. The code need be
 *  updated to keep track of how many threads are created for PTCs
 *  such that thr_join is not attempted for the MscPmDispatcherThread.
 *
 *---------------------------------------------------------------------
 *
 *  Example MSC style trace of this interface and TTCN code:
 *
 *                                              POSTMASTER/MSCE
 *  MTC                                                 :
 *   |                                                  |
 *  MscPmInit() - - - - - > MscPmDispatcherThread       |
 *   |                                |                 |
 *   |                             SPInit()------------>|
 *   |                                |                 |
 *  CREATE(PTC)- - > PTC              |                 |
 *   |                |               |                 |
 *  MscLogCreate()------------>SPSend()/SPRead()<------>|
 *   |                |               |                 |
 *   |         MscLogSend()--->SPSend()/SPRead()<------>|
 *   |                |               |                 |
 *   |                X               |                 |
 *  MscLogDone(PTC)----------->SPSend()/SPRead()<------>|
 *   |                                |                 |
 *  MscPmExit() --------------------->|                 |
 *   |                            SPExit()              |
 *   X                                X                 |
 *                                                      :
 *
 *--------------------------------------------------------------------
 *
 *   Please see associated file mscpm.c for detailed comments and
 *   implementation detail.
 */



/*--------------------------------------------------------------------
 *  Name:  MscPmInit
 *  Description:
 *
 *  1. Initializes internal data.
 *  2. Creates the MscPmDispatcherThread (which in turn will first
 *     call the SPInit function and then start waiting for events
 *     to dispatch).
 */

extern void MscPmInit( void );

/*--------------------------------------------------------------------
 *  Name:  MscPmExit
 *  Description:
 *
 *  1. Send a special 'exit' RPC to the MscPmDispatcherThread, which
 *     will terminate.
 *  2. Free any internal data (semaphores etc.).
 */

extern void MscPmExit( void );

/*--------------------------------------------------------------------
 *  Name:  MscPmDoRPC
 *  Description:
 *
 *  1. Wait for any pending RPC to terminate
 *  2. Send a RPC request to the MscPmDispatcherThread
 *  3. Wait (forever) for a reply from the MscPmDispatcherThread
 *  4. Allow other threads to do RPCs
 *
 *  Parameters are:
 *     tool     - The tool as defined in tau public interface description
 *     mtype    - A message type corresponding to a rpc request as defined
 *                in the Tau public interface.
 *     iobuffer - I/O parameter: pointer to a buffer containing the
 *                message, sufficiently large to contain the response
 *                to the RPC. Note that the replies needed for MSC
 *                generation are not expected to hold more data than
 *                some few integer values.
 */

extern void MscPmDoRPC( int tool, int mtype, char * iobuffer );


#endif /* MSCPM_H */