/* begincopyright
  Copyright (c) 1988 Xerox Corporation. All rights reserved.
  Use and copying of this software and preparation of derivative works based
  upon this software are permitted. Any distribution of this software or
  derivative works must comply with all applicable United States export
  control laws. This software is made available AS IS, and Xerox Corporation
  makes no warranty about the software, its performance or its conformity to
  any specification. Any person obtaining a copy of this software is requested
  to send their name and post office or electronic mail address to:
    PCR Coordinator
    Xerox PARC
    3333 Coyote Hill Rd.
    Palo Alto, CA 94304
  endcopyright */

/*
 * ThreadsSlaveIOP.h
 *
 *
 * Demers, January 10, 1990 11:01:07 am PST
 */

#ifndef _XR_THREADS_SLAVE_IOP_
#define _XR_THREADS_SLAVE_IOP_

#include "xr/Threads.h"
#include "xr/ThreadsBackdoor.h"

typedef XR_IOPE XR_Slave;


extern XR_Slave
XR_SlaveStart();
/*
    Start a new slave IOProcessor, and return it.
    On error: return NIL; error code in XR_GetErrno().
*/


extern void
XR_SlaveStop(/* XR_Slave slave */);
/*
    Stop a slave IOProcessor.
    Use this to free up resources.
*/



typedef int (*XR_SlaveProc)(/* unsigned clientData */);
/*
    Callback proc to be executed on slave IOProcessor.
    Shares the address space of the PCR threads world, but has its own stack.
    May NOT do thread operations like monitor entry, wait for CV, etc.
    Allowed to do (most) Unix system calls.

    ==> Should immediately return error indication if interrupted (EINTR).
*/


extern int
XR_SlaveCall(/*
    XR_Slave slave,
    XR_SlaveProc proc,
    unsigned clientData,
    XR_Ticks timeout
*/);
/*
    The effect is

	result = (*proc)(clientData)

    where proc is executed on the specified slave IOProcessor.

    The calling thread may use XR_GetErrno() to determine the errno value that
    existed on the IOProcessor when proc returned.

    Special case: if the call is aborted or times out, result is (-1),
    and XR_GetErrno() returns either XR_EABORTED or ETIMEDOUT, as appropriate.
*/


extern int
XR_SlaveCallM(/* 
    XR_Slave slave,
    XR_MesaProc mp,
    XR_Ticks timeout
*/);
/*
    Like XR_SlaveCall, above.
*/


/*
 *
 * Worker procs
 *
 * One of the things a SlaveProc can do is install a WorkerProc
 *   on its IOP (see ThreadsBackdoor.h).
 *
 * Worker proc takes no arguments, is invoked on the IOP with 
 *   signals disabled (it may enable/disable them, but should
 *   return with signals disabled).
 */

typedef bool (*XR_SlaveWorkerProc)();
/*
    (Result == TRUE) ==> don't need to wait for interrupt before
      checking for orders and calling worker proc again ...
*/

extern void
XR_InstallSlaveWorkerProc(/*
    XR_SlaveWorkerProc proc;
*/);
/*
    Install proc as worker proc on current IOP.
    To be called only from code running on an IOP (e.g. a SlaveProc).
*/

extern void
XR_SlaveCheckOrders();
/*
    Check to see if orders have been issued to this IOP, and if so execute
      them.
    Orders are always executed with signals disabled; the signal state is
      saved and restored around calling the orders proc.
    To be called only from code running on an IOP.
*/

#endif /* _XR_THREADS_SLAVE_IOP_ */