pithread.h

mini http server,可以集成嵌入到程序中,实现简单的web功能

/*____________________________________________________________________________*\
 *

 Copyright (c) 1997-2003 John Roy, Holger Zimmermann. All rights reserved.

 These sources, libraries and applications are
 FREE FOR COMMERCIAL AND NON-COMMERCIAL USE
 as long as the following conditions are adhered to.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:

 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer. 

 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.

 3. The name of the author may not be used to endorse or promote products
    derived from this software without specific prior written permission.

 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 IN NO EVENT SHALL THE AUTHORS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGE.

 *____________________________________________________________________________*|
 *
 * $Source: /cvsroot/pi3web/Pi3Web_200/Source/PiAPI/PIThread.h,v $
 * $Date: 2003/06/12 18:32:56 $
 *
 Description:
\*____________________________________________________________________________*/
/* $HeaderTop:$ */

#ifndef PITHREAD_H_
#define PITHREAD_H_

#include "PiAPI.h"

/*____________________________________________________________________________*\
 *
 Typedefs:
\*____________________________________________________________________________*/
typedef struct Thread PIThread;
typedef struct Allocator PIMemoryPool;
typedef unsigned long (* PIThreadFn)( unsigned long);

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_new

 Synopsis:
	PIThread *PIThread_new( PIMemoryPool *pPool, int iStackSize )

 Description:
	Creates and initializes a new thread object. The function PIThread_begin()
	can be used to run the thread.

	The parameters pPool and iStackSize are for future use but 
	the values NULL and 0 respectively should be used to ensure
	future compatibility.

 Notes:
	If successful a new thread object will be created but will not
	be executed.
	
	The pointer to the thread object remains valid until PIThread_delete() is	
	called.

 Return Values:
	On success PIThread_new() returns a pointer to a new
	thread object.

 Errors:
	On error PIThread_new() returns NULL.

	PIPlatform_getLastError() can be used to obtain more detailed
	error information.

 See Also:
	PIThread_delete().
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIThread *PIThread_new( PIMemoryPool *pPool, int iStackSize );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_begin

 Synopsis:
	int PIThread_begin( PIThread *pThread, PIThreadFn fnEntry,
		unsigned long ulData, int iPriority, int iFlags )

 Description:
	Schedules the thread object pThread to be executed. The entry point
	function fnEntry will invoked with the argument ulData.

	The value iPriority can be one of the thread priority values 
	described in PIThread_setPriority() and indicates the initial
	priority at which the thread runs.

	The value of iFlags is formed by OR'ing together zero or more of
	the following values:-

		PITHREAD_FLAGS_SUSPENDED	The thread not run until PIThread_resume()

 Notes:
	The thread object pThread can be a newly created object from 
	PIThread_new() or a previously run thread which has terminated.
	
 Return Values:
	On success PIThread_begin() returns zero (PIAPI_COMPLETED).

 Errors:
	PIAPI_ERROR		if an error occurred.

	PIPlatform_getLastError() can be used to obtain more detailed error
	information. 

 See Also:
	PIThread_terminate(), PIThread_waitForThread().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_begin( PIThread *pThread, PIThreadFn fnEntry,
    unsigned long ulData, int iPriority, int iFlags );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_terminate

 Synopsis:
	int PIThread_terminate( PIThread *pThread, unsigned long ulExitCode )

 Description:
	Schedules the specified thread for termination. The thread will exit
	with the status code ulExitCode.
	
 Notes:
	** IMPORTANT **
	Use of this function is not recommended as the target thread will
	usually have no opportunity to cleanup critical activity or
	synchronized actions it may be performing. This can cause the state
	of global objects to become unstable. This is true for user context
	threads, and particularly true for some operating system threads 
	implementations.

	PIThread_terminate is not guaranteed to wait for the thread to 
	terminate. Use the function PIThread_waitForThread() after
	PIThread_terminate() to poll for the termination of
	another thread.
	
	If pThread is the main thread then the following actions will also
	occur in the following order:
	<UL>
		<ITEM>PIProgram_enter() will return PIAPI_COMPLETED, if used.
		<ITEM>All other threads will be terminated, and thread objects
			destroyed with PIThread_delete().
		<ITEM>PIPlatform_enter() will return PIAPI_COMPLETED.
	</UL>

 Return Values:
	On success PIThread_terminate returns zero (PIAPI_COMPLETED).

 Errors:
	PIAPI_ERROR		an error occurred.

	PIPlatform_getLastError() can be used to get more specific
	error information.

 See Also:
	PIThread_begin(), PIThread_waitForThread().	
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_terminate( PIThread *pThread,
	unsigned long ulExitCode );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_delete
 
 Synopsis:
	int PIThread_delete( PIThread *pThread )

 Description:
	Destroys a thread object, and invalidates the pointer pThread.

 Notes:
	If pThread has not terminated, PIThread_delete() will kill the thread
	and poll for its termination using PIThread_terminate() and 
	PIThread_waitForThread().

	PIThread_delete completely invalidates the pointer pThread, the 
	results are undefined if the pointer pThread is used in a thread function
	again. A defensive use of this function would set pThread to NULL after
	PIThread_delete() has been successfully completed.

 Return Values:
	On success PIThread_delete() returns zero (PIAPI_COMPLETED). 

 Errors:
	PIAPI_ERROR		if an error occurred.

	PIPlatform_getLastError() can be used to get more specific error
	information.

 See Also:
	PIThread_new().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_delete( PIThread *pThread );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_suspend

 Synopsis:
	int PIThread_suspend( PIThread *pThread )

 Description:
	Suspends execution of the thread pThread.

 Notes:
 Return Values:
	PIThread_suspend() return zero (PIAPI_COMPLETED) if the thread was
	succesfully suspended or if the thread had previously been suspended.

 Errors:
	PIAPI_ERROR 	if an error occurred.

	PIPlatform_getLastError() can be used to get more specific error
	information.

 See Also:
	PIThread_resume().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_suspend( PIThread *pThread );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_resume
	
 Synopsis:
	int PIThread_resume( pThread )

 Description:
	Resumes execution of a thread.

 Notes:

 Return Values:
	PIThread_resume() returns zero (PIAPI_COMPLETED) if the thread was
	succesfully resumed or if the thread was not suspended.

 Errors:
	PIAPI_ERROR		if an error occurred.

	PIPlatform_getLastError() can be used to get more specific error
	information.

 See Also:
	PIThread_suspend().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_resume( PIThread *pThread );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_getSystemHandle

 Synopsis:
	void *PIThread_getSystemHandle( PIThread *pThread )

 Description:
	Returns the implementation specific handle or pointer of the thread.
	This value can be used to reference the thread in additional thread
	library functions supplied by the operating system.

 Notes:
	The value returned by PIThread_getSystemHandle() must be cast to the 
	appriopriate type e.g. 'thread_t', 'HANDLE'. 

 Return Values:
	On success PIThread_getSystemHandle() returns the specific 
	operating system handle of the thread.

 Errors:
	The function PIPlatform_getLastError() must be used to determine
	if a handle value of NULL is an error or the valid system
	dependant handle of the current thread.

	PIPlatform_getLastError() can be used to get more specific error
	information.

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI void *PIThread_getSystemHandle( PIThread *pThread );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_yield

 Synopsis:
	int PIThread_yield()

 Description:
	Yield processing to another thread.

 Notes:
	PIThread_yield() does not attempt to terminate the thread
	referenced by pThread, the function PIThread_terminate() can be used
	for that.
	When multithreading is implemented using the kernel threads
	implementation of the current operating system with function will
	invoke the appropriate theads system call to cause the current
	thread to yield.
	PIThread_yield() does not guarantee that the current thread will
	yield. This is especially true when no other threads of equal or
	greater priority are runnable.
	
 Return Values:
	On success PIThread_yield() returns zero (PIAPI_COMPLETED).

 Errors:
	PIAPI_ERROR 	if an error occurred.

	PIPlatform_getLastError() can be used to get more specific error
	information.

 See Also:
	PIThread_userYield().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_yield();

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_userYield