pithread.h

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

 Synopsis:
	int PIThread_userYield()

 Description:
	Yield processing to another user thread. This function has no
	effect when multi-threading is implemented with operating system
	specific kernel threads.
	When multithreading is implemented with user context threads this
	function will behave like PIThread_Yield().

 Notes:
	Unlike kernel supplied threads (operating system specific) 
	user context threads will not context switch until a synchronization	
	function, such as PISync_lock(), PIPlatform_pollNetFD() is invoked. In
	code which does not use these synchronization functions (such as 
	complex mathematical algorithms) one thread would monopolize all the
	processing in the application. PIThread_userYield() can be inserted into
	such code as a portable way to force preemptive thread behaviour
	in a non-preemptive threads environment without added unnecessary 
	PIThread_Yield() calls to kernel multithreading environments.
	
 Return Values:
	On success PIThread_userYield() 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_yield().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_userYield();

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_waitForThread

 Synopsis:
	int PIThread_waitForThread( PIThread *pThread );

 Description:
	Suspends execution of the current thread until the thread referenced
	by pThread has terminated.

 Notes:
	PIThread_waitForThread() does not attempt to terminate the thread
	referenced by pThread, the function PIThread_terminate() can be used
	for that.
	
 Return Values:
	PIThread_waitForThread() returns zero (PIAPI_COMPLETED) if the 
	thread referenced by pThread has terminated.
 
 Errors:
	PIAPI_ERROR		if an error occurred.

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

 See Also:
	PIThread_terminate().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_waitForThread( PIThread *pThread );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_initThreadKey

 Synopsis:
	int PIThread_initThreadKey()

 Description:
	Returns a new key (index) that can be used in PIThread_setData() and
	PIThread_getData() to save and retrieve thread local data.

 Notes:

 Return Values:
	On success PIThread_initThreadKey() returns a non-negative thread
	key.

 Errors:
	On failure PIThread_initThreadKey() returns a negative number.

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

 See Also:
	PIThread_destroyThreadKey().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_initThreadKey();

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_destroyThreadKey

 Synopsis:
	int PIThread_destroyThreadKey( int iKey )

 Description:
	Destroy the thread key (index) iKey. This key can subsequently be 
	reassigned by PIThread_initThreadKey().

 Notes:

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

 Errors:
	On failure PIThread_destroyThreadKey() returns PIAPI_ERROR.

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

 See Also:
	PIThread_initThreadKey().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_destroyThreadKey( int iKey );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_setData

 Synopsis:
	int PIThread_setData( PIThread *pThread, int iKey, void *pData )

 Description:
	Sets the local data to pData for the thread referenced by pThread 
	at the key iKey.

 Notes:

 Return Values:
	On success PIThread_setData() 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_getData().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_setData( PIThread *pThread, int iKey, void *pData );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_getData

 Synopsis:
	void *PIThread_getData( PIThread *pThread, int iKey )

 Description:
	Returns the thread local data for the thread referenced by pThread
	at key iKey. This is the value previously set by PIThread_setData() for
	this thread and key.

 Notes:
	All thread local data is zero initialized by PIThread_new(). 
	It is undefined whether using PIThread_terminate() followed by
	PIThread_begin() will modify thread local data when used to reuse a
	thread.
	
 Return Values:
	On success PIThread_getData() returns the thread local data for
	this thread object at the specified key and PIPlatform_getLastError()
	will return PIAPI_COMPLETED.

 Errors:
	On error PIThread_getData() will return NULL and PIPlatform_getLastError()
	will return a specific error code.

 See Also:
	PIThread_setData().
\*____________________________________________________________________________*/
PUBLIC_PIAPI void *PIThread_getData( PIThread *pThread, int iKey );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_getCurrent

 Synopsis:
	PIThread *PIThread_getCurrent()

 Description:
	Returns a pointer to the currently executing thread object.

 Notes:

 Return Values:
	On success PIThread_getCurrent() returns the non-NULL pointer 
	to the currently executing thread object.

 Errors:
	NULL 	if an error occurs.

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

 See Also:
	PIThread_getMain().
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIThread *PIThread_getCurrent();

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_getMain

 Synopsis:
	PIThread *PIThread_getMain()

 Description:
	Returns a pointer to the main thread for the process.

 Notes:
 Return Values:
	On success PIThread_getMain() returns the non-NULL pointer 
	to the main thread object.

 Errors:
	NULL 	if an error occurs.

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

 See Also:
	PIThread_getCurrent().
\*____________________________________________________________________________*/
PUBLIC_PIAPI PIThread *PIThread_getMain();

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_getPriority

 Synopsis:
	int PIThread_getPriority( PIThread *pThread, int *piPriority )

 Description:
	Returns the priority of the thread pThread. piPriority points
	to the location where the priority will be written.

 Notes:
	See PIThread_setPriority() for a description of thread priorities.

 Return Values:
	On success PIThread_getPriority() write the thread priority into
	piPriority and returns zero (PIAPI_COMPLETED).

 Errors:
	PIAPI_ERROR		if an error occurs.

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

 See Also:
	PIThread_setPriority().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_getPriority( PIThread *pThread, int *piPriority );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_setPriority

 Synopsis:
	int PIThread_setPriority( PIThread *pThread, int iNewPriority )

 Description:
	Set the priority of the thread pThread. The following are valid
	priority values.

	<TABLE>
	<TR>	PITHREAD_PRIORITY_LOWEST
	<TR>	PITHREAD_PRIORITY_LOW
	<TR>	PITHREAD_PRIORITY_MED
	<TR>	PITHREAD_PRIORITY_HIGH
	<TR>	PITHREAD_PRIORITY_HIGHEST
	</TABLE>

 Notes:
	The precise behaviour of threads and thread priorities varies
	greatly across implementations. In general a higher priority
	thread will be scheduled before and run for longer than a
	lower priority thread. However whether or not a lower priority
	thread with be scheduled AT ALL when higher priority threads
	are runnable is implementation defined. 

	The main thread initially runs at priority PITHREAD_PRIORITY_MED.

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

 Errors:
	PIAPI_ERROR		if an error occurs.

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

 See Also:
	PIThread_getPriority().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIThread_setPriority( PIThread *pThread, int iNewPriority );

/*____________________________________________________________________________*\
 *
 Name:
	PIThread_dbgDump

 Synopsis:
	void PIThread_dbgDump( const char *pDumpFile )

 Description:
	Opens the specified file for write append and writes internal
	information on thread status within the program.
	If pDumpFile is NULL, information will be written to the stdout stream.

 Notes:
	This function is mainly for getting verbose information on 
	thread scheduling when the internal user thread implementation is
	being used. 
	If operating system kernel threads are used this debugging  
	information will be terse.

 Return Values:
	PIThread_dbgDump does not return a value.

 Errors:
	PIThread_dbgDump does not return errors.

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

 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI void PIThread_dbgDump( const char *pDbgDump );

#endif	/* PITHREAD_H_ */