This module defines portable thread and mutex functions. More...

Macros
#define	THREAD_TYPE
	Type of a thread (thread ID) More...

#define	THREAD_ID
	The thread ID of self. More...

#define	THREAD_CREATE(tidptr, funcptr, argptr)
	Create a new thread. More...

#define	THREAD_CREATEX(tidptr, funcptr, argptr)
	Create a new joinable thread (Windows only) More...

#define	THREAD_CLOSE(tid)
	Close the thread ID handle created by `THREAD_CREATEX` (Windows only) More...

#define	THREAD_DETACH(tid)
	Detach a thread. More...

#define	THREAD_JOIN(tid)
	Join a thread. More...

#define	THREAD_EXIT
	Exit the current thread. More...

#define	THREAD_CANCEL(tid)
	Cancel a thread. More...

#define	MUTEX_TYPE
	Type of a mutex object. More...

#define	MUTEX_INITIALIZER
	Mutex initializer object. More...

#define	MUTEX_SETUP(mx)
	Mutex object initialization. More...

#define	MUTEX_CLEANUP(mx)
	Mutex object finalization. More...

#define	MUTEX_LOCK(mx)
	Mutex object lock. More...

#define	MUTEX_UNLOCK(mx)
	Mutex object unlock. More...

#define	COND_TYPE
	The type of a condition variable. More...

#define	COND_SETUP(cv)
	Condition variable initialization. More...

#define	COND_CLEANUP(cv)
	Condition variable finalization. More...

#define	COND_SIGNAL(cv)
	Condition variable signal operation. More...

#define	COND_WAIT(mx, cv)
	Condition variable wait operation. More...

Detailed Description

This module defines portable thread and mutex functions.

THREAD_TYPE
THREAD_ID
THREAD_CREATE(tidptr, funcptr, argptr)
THREAD_CREATEX(tidptr, funcptr, argptr) (for Windows)
THREAD_CLOSE(tid) (for Windows)
THREAD_DETACH(tid)
THREAD_JOIN(tid)
THREAD_EXIT
THREAD_CANCEL(tid)
MUTEX_TYPE
MUTEX_INITIALIZER
MUTEX_SETUP(mx)
MUTEX_CLEANUP(mx)
MUTEX_LOCK(mx)
MUTEX_UNLOCK(mx)
COND_TYPE
COND_SETUP(cv)
COND_CLEANUP(cv)
COND_SIGNAL(cv)
COND_WAIT(mx, cv)

Macro Definition Documentation

#define COND_CLEANUP ( cv )

Condition variable finalization.

This macro finalizes the specified condition variable.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Parameters

cv	`COND_TYPE` condition variable

#define COND_SETUP ( cv )

Condition variable initialization.

This macro initializes the specified condition variable.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Parameters

cv	`COND_TYPE` condition variable

#define COND_SIGNAL ( cv )

Condition variable signal operation.

This macro signals the specified condition variable.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Parameters

cv	`COND_TYPE` condition variable

#define COND_TYPE

The type of a condition variable.

This macro represents a portable condition variable

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

#define COND_WAIT	(	mx,
		cv
	)

Condition variable wait operation.

This macro waits on the specified condition variable and releases the mutex while waiting.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Parameters

mx	`MUTEX_TYPE` mutex object
cv	`COND_TYPE` condition variable

#define MUTEX_CLEANUP ( mx )

Mutex object finalization.

This macro finalizes a mutex object.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Example:

#include "plugin/threads.h"
MUTEX_TYPE lock;
MUTEX_SETUP(lock);
... // some other work to do
MUTEX_LOCK(lock);
... // critical section
MUTEX_UNLOCK(lock);
... // some other work to do
MUTEX_CLEANUP(lock);

Parameters

mx	`MUTEX_TYPE` mutex object

#define MUTEX_INITIALIZER

Mutex initializer object.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Example:

#include "plugin/threads.h"
static MUTEX_TYPE lock = MUTEX_INITIALIZER;
int main()
{
  ... // some other work to do
  MUTEX_LOCK(lock);
  ... // critical section
  MUTEX_UNLOCK(lock);
  ...
}

#define MUTEX_LOCK ( mx )

Mutex object lock.

This macro acquires mutex.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Example:

#include "plugin/threads.h"
MUTEX_TYPE lock;
MUTEX_SETUP(lock);
... // some other work to do
MUTEX_LOCK(lock);
... // critical section
MUTEX_UNLOCK(lock);
... // some other work to do
MUTEX_CLEANUP(lock);

Parameters

mx	`MUTEX_TYPE` mutex object

#define MUTEX_SETUP ( mx )

Mutex object initialization.

This macro initializes a mutex object.

To declare and initialize static mutex objects, see MUTEX_INITIALIZER.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Example:

#include "plugin/threads.h"
MUTEX_TYPE lock;
MUTEX_SETUP(lock);
... // some other work to do
MUTEX_LOCK(lock);
... // critical section
MUTEX_UNLOCK(lock);
... // some other work to do
MUTEX_CLEANUP(lock);

Parameters

mx	`MUTEX_TYPE` mutex object

#define MUTEX_TYPE

Type of a mutex object.

This macro represents a portable mutex object type.

To declare and initialize static mutex objects, see MUTEX_INITIALIZER.

Example:

#include "plugin/threads.h"
MUTEX_TYPE lock;
MUTEX_SETUP(lock);
... // some other work to do
MUTEX_LOCK(lock);
... // critical section
MUTEX_UNLOCK(lock);
... // some other work to do
MUTEX_CLEANUP(lock);

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

#define MUTEX_UNLOCK ( mx )

Mutex object unlock.

This macro releases mutex.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Example:

#include "plugin/threads.h"
MUTEX_TYPE lock;
MUTEX_SETUP(lock);
... // some other work to do
MUTEX_LOCK(lock);
... // critical section
MUTEX_UNLOCK(lock);
... // some other work to do
MUTEX_CLEANUP(lock);

Parameters

mx	`MUTEX_TYPE` mutex object

#define THREAD_CANCEL ( tid )

Cancel a thread.

This macro requests that the specified thread be cancelled.

POSIX threads can be cancelled when currently in a cancellation point, which are certain functions that will terminate the thread when the thread is cancelled.

Warning: Cancelling a thread may lead to resource leaks when the thread has no mechanism to clean up its state (memory allocated, files and sockets opened etc.), unless cleanup handlers are defined for each thread, e.g. with pthread_cleanup_push. Even when defining a cleanup function, care must be taken to prevent resource leaks that may be caused by cancellation points that sit between a resouce acquisition operation and its release operation, e.g. between a file open and close operation some read/write functions may be called that are cancellation points. The gSOAP engine and plugins are designed to maintain the engine state using resource pointers to resources (memory, files, sockets etc.) in the soap context. The context should be passed to the cleanup function when added with pthread_cleanup_push to cleanup the context. This cleanup function should call soap_destroy, soap_end, and soap_free (in that order). However, use THREAD_CANCEL at your own risk. User-defined service operations and other non-gSOAP code may not meet the requirements to perform a safe THREAD_CANCEL unless the cleanup functions are carefully designed. Alternatively, a simpler approach with a global flag (a flag per thread) may suffice: set the flag by the main thread to indicate termination is requested of the specific thread and check this flag in the user-defined service operations to terminate the service operation with an error, e.g. return 500.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Example:

#include "soapH.h"
#include "plugin/threads.h"
struct soap *soap = soap_new();
soap->bind_flags = SO_REUSEADDR;            // immediate port reuse
soap->accept_timeout = 3600;                // exit loop when no request arrives in one hour
soap->send_timeout = soap_recv_timeout = 5; // 5 seconds max socket stall time (unlimited by default)
soap->transfer_timeout = 30;                // 30 seconds max message transfer time (unlimited by default)
soap->recv_maxlength = 1048576;             // limit messages received to 1MB (2GB by default)
if (soap_valid_socket(soap_bind(soap, NULL, PORTNUM, BACKLOG)))
{
  while (1)
  {
    if (soap_valid_socket(soap_accept(soap)))
    {
      THREAD_TYPE tid;
      struct soap *tsoap = soap_copy(soap);
      if (!tsoap)
        soap_force_closesock(soap);
      else
        while (THREAD_CREATE(&tid, (void*(*)(void*))&accept_request, (void*)tsoap))
          sleep(1); // failed, try again
    }
    else if (soap->errnum) // accept failed, try again after 1 second
    {
      soap_print_fault(soap, stderr);
      sleep(1);
    }
    else // accept_timeout timed out, quit looping
    {
      break;
    }
    soap_destroy(soap);
    soap_end(soap);
  }
}
soap_free(soap);
void *accept_request(struct soap *soap)
{
  THREAD_TYPE tid;
  struct soap *tsoap;
  THREAD_DETACH(THREAD_ID);
  // create a new thread that is timed to execute for max 10 seconds
  tsoap = soap_copy(soap);
  if (!tsoap)
  {
    soap_force_closesock(soap);
  }
  else
  {
    while (THREAD_CREATE(&tid, (void*(*)(void*))&process_request, (void*)tsoap))
      sleep(1); // failed, try again
    // allow serving the request by the new thread for up to 30 seconds max
    sleep(30);
    // terminate process_request thread
    THREAD_CANCEL(tid);
  }
  // clean up
  soap_destroy(soap);
  soap_end(soap);
  soap_free(soap);
  return NULL;
}
void *process_request(struct soap *soap)
{
  // add the cleanup function
  pthread_cleanup_push((void(*)(void*))&cleanup, (void*)soap);
  soap_serve(soap);
  // remove the cleanup function and call it to cleanup the context
  pthread_cleanup_pop(1);
  return NULL;
}
void cleanup(struct soap *soap)
{
  soap_destroy(soap);
  soap_end(soap);
  soap_free(soap);
}

Parameters

tid	`THREAD_TYPE` thread ID to cancel

#define THREAD_CLOSE ( tid )

Close the thread ID handle created by THREAD_CREATEX (Windows only)

#define THREAD_CREATE	(	tidptr,
		funcptr,
		argptr
	)

Create a new thread.

This macro creates a new thread and runs the specified function with the argument parameter passed to this function.

Warning: On Windows platforms THREAD_CREATE uses _beginthread which returns a thread ID handle that cannot be joined. To join a thread use THREAD_CREATEX(&tid, func, arg) then THREAD_JOIN. Don't forget to THREAD_CLOSE(tid) afterwards:
#include "plugin/threads.h"
THREAD_TYPE tid;
while (THREAD_CREATEX(&tid, (void*(*)(void*))&process_request, (void*)tsoap)))
sleep(1); // failed, try again
... // some other work to do
THREAD_JOIN(tid); // wait for the thread to terminate and join
THREAD_CLOSE(tid); // close handle
... // some other work to do

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Example:

#include "plugin/threads.h"
THREAD_TYPE tid;
while (THREAD_CREATE(&tid, (void*(*)(void*))&process_request, (void*)tsoap)))
  sleep(1); // failed, try again
... // some other work to do
THREAD_JOIN(tid); // optional: to wait for the thread to terminate and join (see warning)
... // some other work to do

Parameters

tidptr	pointer to `THREAD_TYPE` thread ID to assign
funcptr	function to run by the new thread
argptr	the argument (a pointer) to pass to the function when called

Returns: zero on success and nonzero on failure

#define THREAD_CREATEX	(	tidptr,
		funcptr,
		argptr
	)

Create a new joinable thread (Windows only)

On Windows platforms THREAD_CREATE uses _beginthread which returns a thread ID handle that cannot be joined. To join a thread use THREAD_CREATEX(&tid, func, arg) then THREAD_JOIN. Don't forget to THREAD_CLOSE(tid) afterwards.

#define THREAD_DETACH ( tid )

Detach a thread.

This macro detaches the specified thread. A detached thread cannot be joined back with the thread that created it. When a detached thread terminates, its resources are automatically released back to the system without the need for another thread to join with the terminated thread.

This macro has no effect on Windows platforms, see THREAD_CREATE.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Example:

#include "plugin/threads.h"
THREAD_DETACH(THREAD_ID); // detach self

Parameters

tid	`THREAD_TYPE` thread ID to detach

#define THREAD_EXIT

Exit the current thread.

This macro terminates the current thread.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

#define THREAD_ID

The thread ID of self.

This macro represents the current thread ID, i.e. self.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

#define THREAD_JOIN ( tid )

Join a thread.

This macro waits for the termination of the specified thread to join it.

This macro requires THREAD_CREATEX and THREAD_CLOSE on Windows plaforms.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Parameters

tid	`THREAD_TYPE` thread ID to join

#define THREAD_TYPE

Type of a thread (thread ID)

This macro represents a portable thread ID type.

Note: This macro is declared in gsoap/plugin/threads.h and requires compilation of gsoap/plugin/threads.c on Windows platforms.

Example:

THREAD_TYPE tid;
while (THREAD_CREATE(&tid, (void*(*)(void*))&process_request, (void*)tsoap)))
  sleep(1); // failed, try again

Macros

Detailed Description

Macro Definition Documentation