/* 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← */