/*
*  Multithreaded Demo Source
* 
*  Copyright (C) 1995 by Sun Microsystems, Inc.
*  All rights reserved.
* 
*  This file is a product of SunSoft, Inc. and is provided for
*  unrestricted use provided that this legend is included on all
*  media and as a part of the software program in whole or part.
*  Users may copy, modify or distribute this file at will.
* 
*  THIS FILE IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING
*  THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
*  PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
* 
*  This file is provided with no support and without any obligation on the
*  part of SunSoft, Inc. to assist in its use, correction, modification or
*  enhancement.
* 
*  SUNSOFT AND SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT
*  TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS
*  FILE OR ANY PART THEREOF.
* 
*  IN NO EVENT WILL SUNSOFT OR SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY
*  LOST REVENUE OR PROFITS OR OTHER SPECIAL, INDIRECT AND CONSEQUENTIAL
*  DAMAGES, EVEN IF THEY HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH
*  DAMAGES.
* 
*  SunSoft, Inc.
*  2550 Garcia Avenue
*  Mountain View, California  94043
*/
  
  SPILT - Solaris to POSIX Interface Layer for Threads.
  
  This code is public-domain, it may be freely distributed provided the
  Copyright notice is retained. This code is not supported in any way.
  Usage of the code is solely at the user's/programmer's discretion.
  Sun Microsystems makes no claim as to the reliabilty, correctness or
  suitability of this code. Sun Microsystems will not be held liable in
  any way as a result loss or damage arising from the use this code.
  
  This package implements an interface mapping between Solaris threads and
  POSIX.1c threads. The POSIX.1c material is based on the May 1994/D9 document.
  
  This package should make porting Solaris thread source to a POSIX.1c based
  library a matter of "wedging" this interface between the Solaris thread
  source and the POSIX.1c library.
  
  In producing the package, the goal was to acheive a high degree of mapping
  between Solaris and POSIX.1c. However, certain aspects of Solaris either
  do not have a POSIX.1c equivalent have only an "approximate" equivalent.
  Another small set of Solaris features can only be mapped into a POSIX.1c
  implementation if the implementation supports the corresponding feature.
  
  The package uses two macros to control the characteristics of the
  package. If the macro SPILT_MACROS is defined then certain functions
  and typedef's will be implemented as macros to the POSIX.1c equivalent
  functions and typedef's. Otherwise, all functions and typedefs are
  strictly defined in the compilation. The second macro is SPILT_LIBERAL,
  refered to as the "test macro". This macro is built up from the bit-wise
  or'ing of _SPILT_LIBERAL_* macros. The "liberal" macros allows the
  package builder to control how tolerant the package will be of semantic
  incompleteness.
  
  The following points describe the "approximate" mappings, how they are
  implemented and how the _SPILT_LIBERAL_* macro controls behavior.
  
  THR_DAEMON
  	The thread create option for daemon threads has no equivalent in
  	POSIX.1c (ENOTSUP). If the test macro includes the
  	_SPILT_LIBERAL_DAEMON flag the option is silently ignored.
  
  THR_SUSPENDED
  	The thread create option for suspended threads has no equivalent
  	in POSIX.1c (ENOTSUP). If the test macro includes the
  	_SPILT_LIBERAL_SUSPENDED flag the option is silently ignored.
  
  THR_NEW_LWP
  	The thread create option for new LWPs has no equivalent in POSIX.1c
  	(ENOTSUP). If the test macro includes the _SPILT_LIBERAL_NEW_LWP
  	flag the option is silently ignored.
  
  thr_setconcurrency
  	This function has no equivalent mapping in POSIX.1c (ENOSYS). If          
  	the test macro includes the _SPILT_LIBERAL_SETCONCURRENCY flag
  	the funciton will return success (0).
  
  thr_getconcurrency
  	This function has no equivalent mapping in POSIX.1c (ENOSYS). If          
  	the test macro includes the _SPILT_LIBERAL_GETCONCURRENCY flag
  	the function will always return zero (0).
  
  thr_suspend
  	This function has no equivalent mapping in POSIX.1c (ENOSYS). If          
  	the test macro includes the _SPILT_LIBERAL_SUSPEND flag the
  	function will always return success (0).
  
  thr_continue
  	This function has no equivalent mapping in POSIX.1c (ENOSYS). If          
  	the test macro includes the _SPILT_LIBERAL_CONTINUE flag the
  	function will always return success (0).
  
  thr_create
  	If the POSIX.1c macro _POSIX_THREAD_PRIORITY_SCHEDULING is defined
  	the pthread inheretsched attribute will be set to
  	PTHREAD_INHERIT_SCHED.
  
  THR_BOUND
  	The thread create option for "bound" threads is only supported in
  	POSIX.1c if the macro _POSIX_THREAD_PRIORITY_SCHEDULING is defined.
  	Attempts to use THR_BOUND when the option is not supported will
  	return failure (ENOTSUP). If the test macro includes the
  	_SPILT_LIBERAL_BOUND flag the THR_BOUND option will be ignored if
  	not supported.
  
  stack
  	The thread create attribute for stack address is only supported if
  	the macro _POSIX_THREAD_ATTR_STACKADDR is defined. Attempts to use
  	the stack option when the option is not supported will return
  	failure (ENOTSUP). If the test macro includes the
  	_SPILT_LIBERAL_STACKADDR flag the stack option will be ignored
  	if not supported.
  
  stacksize
  	The thread create option for stack size is only supported if the
  	macro _POSIX_THREAD_ATTR_STACKSIZE is defined. Attempts to use
  	the stacksize option when the attribute is not supported will
  	return failure (ENOTSUP). If the test macro include the
  	_SPILT_LIBERAL_STACKSIZE flag the stacksize option will be
  	ignored if not supported.
  
  thr_setprio
  	The thread priority management is only supported if the macro
  	_POSIX_THREAD_PRIORITY_SCHEDULING is defined. Attempts to use
  	thread scheduling will return failure (ENOSYS). If the test macro          
  	includes the _SPILT_LIBERAL_SETPRIO flag attempts to modify
  	thread priority will always return success (0).
  
  	[Note: Thread priority managment is crudely mapped onto POSIX.1c
  	scheduling (if supported by the implementation), since POSIX.1c
  	supports multiple thread scheduling classes (SCHED_FIFO, SCHED_RR,
  	SCHED_OTHER and possibly others) and Solaris only has one
  	scheduling class. The implemenation here is analogeous to allowing
  	a process to modify its priority without being able to determine
  	1) its scheduling class and 2) the bounds of allowable priority
  	values.]
  
  thr_getprio
  	The thread priority management is only supported if the macro
  	_POSIX_THREAD_PRIORITY_SCHEDULING is defined. Attempts to use
  	thread scheduling will return failure (ENOSYS). If the test macro          
  	includes the _SPILT_LIBERAL_GETPRIO flag attempts to retrieve
  	thread priority will always return success (0).
  
  thr_join
  	POSIX.1c does not support the "non-targeted" join. Attempts 
  	to do so are undefined.
  
  
  XXX_init
  	Solaris synchronization variables are initialized to a default
  	state (USYNC_THREAD) by zero filling the variable. This is
  	achieved when the variable has external scope, i.e. it does not
  	have to be explicitly initialized, because ANSI C states that
  	all uninitialized, external data is zero-filled. In contrast,
  	POSIX.1c requires external synchronization objects to be
  	initialized by assignment of a type-specific macro. The result
  	of these differences is that to ensure "correct" semantics
  	of external Solaris synchronization objects when ported to
  	a POSIX.1c environment is that they must be initialized using
  	the appropriate XXX_init function.
  
  Written by Richard.Marejka@Canada.Sun.COM
  Copyright (c) 1994, by Sun Microsystems, Inc.

----------------------------------------------------------------------------


  	Richard Marejka 	Solaris 2 Migration Support Centre
  	October 6, 1994
        richard@canada.sun.com
  	405-477-1159	
  	
  This package can be used to run a Solaris threads application on a
  system that support POSIX threads.
  
  This package demonstrates that 
  
  a) Solaris threads is not another proprietary threads package - it
     is almost identical to the POSIX proposed standard.
  
  b) Solaris threads programmers need not wait for POSIX to be
     finalized as a standard, before they begin multithreading
     their applications
  
  c) The differences between Solaris threads and POSIX threads
     are primarily syntactic.
  
  In addition, although application programmers may contact OpCom to
  obtain a copy of the SunSoft POSIX.1c EA package, people should be
  aware that the SunSoft package is based on Draft 8 of the POSIX
  standard.   The SunSoft package is not a complete implementation of
  Draft 8. 
  
  
  This package implements Solaris threads in terms of
  POSIX.1c threads. This package allows an application programmer to
  write a Solaris threads program, and then port the application to a
  POSIX.1c based threads implentation.   This package  proves just
  how small the differences are.  
  
  This package should not be used on Solaris systems. At this time
  our POSIX.1c threads are written in terms of Solaris threads.


