Posix thread interface

Functions for starting and managing threads. More...

Files
file	thread.c
	Functions for starting and managing threads.

Data Structures
struct	thread_pvt
	thread struct used to create threads data needs to be first element More...
struct	threadcontainer
	Global threads data. More...

Typedefs
typedef void(*	threadcleanup )(void *)
	Function called after thread termination. More...
typedef void *(*	threadfunc )(void *)
	Thread function. More...
typedef int(*	threadsighandler )(int, void *)
	Thread signal handler function. More...

Enumerations
enum	thread_option_flags { THREAD_OPTION_CANCEL = 1 << 0, THREAD_OPTION_JOINABLE = 1 << 1, THREAD_OPTION_RETURN = 1 << 2 }
	Options supplied to framework_mkthread all defaults are unset. More...
enum	threadopt {   TL_THREAD_NONE = 1 << 0, TL_THREAD_RUN = 1 << 1, TL_THREAD_DONE = 1 << 2, TL_THREAD_JOIN = 1 << 3,   TL_THREAD_STOP = 1 << 4, TL_THREAD_CAN_CANCEL = 1 << 16, TL_THREAD_JOINABLE = 1 << 17, TL_THREAD_RETURN = 1 << 18 }
	Thread status a thread can be disabled by unsetting TL_THREAD_RUN. More...

Functions
int	framework_threadok ()
	let threads check there status. More...
int	startthreads (void)
	Initialise the threadlist and start manager thread. More...
void	stopthreads (int join)
	Signal manager to stop and cancel all running threads. More...
struct thread_pvt *	framework_mkthread (threadfunc func, threadcleanup cleanup, threadsighandler sig_handler, void *data, int flags)
	create a thread result must be unreferenced More...
void	jointhreads (void)
	Join the manager thread. More...
int	thread_signal (int sig)
	Handle signal if its for me. More...

Variables
struct threadcontainer *	threads = NULL
	Thread control data. More...
int	thread_can_start = 1
	Automatically start manager thread. More...

Detailed Description

Functions for starting and managing threads.

See Also

Thread Interface The thread interface consists of a management thread managing a hashed bucket list of threads running optional clean up when done.

Typedef Documentation

typedef void(* threadcleanup)(void *)

Function called after thread termination.

See Also

framework_mkthread()

Parameters

data	Reference of thread data.

Definition at line 238 of file dtsapp.h.

typedef void*(* threadfunc)(void *)

Thread function.

See Also

framework_mkthread()

Parameters

data	Poinnter to reference of thread data.

Definition at line 245 of file dtsapp.h.

typedef int(* threadsighandler)(int, void *)

Thread signal handler function.

See Also

framework_mkthread()

Parameters

data	Reference of thread data.

Definition at line 252 of file dtsapp.h.

Enumeration Type Documentation

enum thread_option_flags

Options supplied to framework_mkthread all defaults are unset.

Note

this is shifted 16 bits limiting 16 options this maps to high 16 bits of threadopt

Enumerator
THREAD_OPTION_CANCEL	Flag to enable pthread_cancel calls this is not recomended and can lead to memory leaks.
THREAD_OPTION_JOINABLE	Create the the thread joinable only do this if you will be joining it cancelable threads are best detached.
THREAD_OPTION_RETURN	Return reference to thread this must be unreferenced.

Definition at line 118 of file dtsapp.h.

                         {
        THREAD_OPTION_CANCEL        = 1 << 0,
        THREAD_OPTION_JOINABLE      = 1 << 1,
        THREAD_OPTION_RETURN        = 1 << 2
};

enum threadopt

Thread status a thread can be disabled by unsetting TL_THREAD_RUN.

Note

bits 16-31 are useoptions see thread_option_flags

Enumerator
TL_THREAD_NONE	No status.
TL_THREAD_RUN	thread is marked as running
TL_THREAD_DONE	thread is marked as complete
TL_THREAD_JOIN	Quit when only manager is left. Note This flag is only valid for manager thread
TL_THREAD_STOP	Quit when only manager is left. Note This flag is only valid for manager thread
TL_THREAD_CAN_CANCEL	Flag to enable pthread_cancel calls.
TL_THREAD_JOINABLE	Flag to enable pthread_cancel calls.
TL_THREAD_RETURN

Definition at line 36 of file thread.c.

               {
    TL_THREAD_NONE      = 1 << 0,
    TL_THREAD_RUN       = 1 << 1,
    TL_THREAD_DONE      = 1 << 2,
    TL_THREAD_JOIN      = 1 << 3,
    TL_THREAD_STOP      = 1 << 4,

    TL_THREAD_CAN_CANCEL    = 1 << 16,
    TL_THREAD_JOINABLE  = 1 << 17,
    TL_THREAD_RETURN    = 1 << 18
};

Function Documentation

struct thread_pvt* framework_mkthread	(	threadfunc	func,
		threadcleanup	cleanup,
		threadsighandler	sig_handler,
		void *	data,
		int	flags
	)

create a thread result must be unreferenced

Note

If the manager thread has not yet started this will start the manager thread.

Warning

THREAD_OPTION_RETURN flag controls the return of this function.

Threads should periodically check the result of framework_threadok() and cleanup or use THREAD_OPTION_CANCEL

Parameters

func	Function to run thread on.
cleanup	Cleanup function to run.
sig_handler	Thread signal handler.
data	Data to pass to callbacks.
flags	Options of thread_option_flags passed

Returns

a thread structure that must be un referencend OR NULL depending on flags.

Definition at line 387 of file thread.c.

References addtobucket(), thread_pvt::cleanup, thread_pvt::data, thread_pvt::flags, thread_pvt::func, threadcontainer::list, threadcontainer::manager, objalloc(), objlock(), objref(), objunlock(), objunref(), setflag, thread_pvt::sighandler, startthreads(), testflag, thread_pvt::thr, thread_can_start, TL_THREAD_RETURN, and TL_THREAD_RUN.

Referenced by nf_ctrack_trace(), startthreads(), and unixsocket_server().

                                                                                                                                          {
    struct thread_pvt *thread;
    struct threadcontainer *tc = NULL;

    /*Grab a reference for threads in this scope start up if we can*/
    if (!(tc = (objref(threads)) ? threads : NULL)) {
        if (!thread_can_start) {
            return NULL;
        } else if (!startthreads()) {
            return NULL;
        }
        if (!(tc = (objref(threads)) ? threads : NULL)) {
            return NULL;
        }
    }

    objlock(tc);
    /* dont allow threads if no manager or it not started*/
    if ((!tc->manager || !func) && (func != managethread)) {
        /*im shuting down*/
        objunlock(tc);
        objunref(tc);
        return NULL;
    } else if (!(thread = objalloc(sizeof(*thread), free_thread))) {
        /* could not create*/
        objunlock(tc);
        objunref(tc);
        return NULL;
    }

    thread->data = (objref(data)) ? data : NULL;
    thread->flags = flags << 16;
    thread->cleanup = cleanup;
    thread->sighandler = sig_handler;
    thread->func = func;
    objunlock(tc);

    /* start thread and check it*/
    if (pthread_create(&thread->thr, NULL, threadwrap, thread) || pthread_kill(thread->thr, 0)) {
        objunref(thread);
        objunref(tc);
        return NULL;
    }

    /*Activate the thread it needs to be flaged to run or it will die*/
    objlock(tc);
    addtobucket(tc->list, thread);
    setflag(thread, TL_THREAD_RUN);
    objunlock(tc);
    objunref(tc);

    if (testflag(thread, TL_THREAD_RETURN)) {
        return thread;
    } else {
        objunref(thread);
        return NULL;
    }
}

int framework_threadok

(

void

)

let threads check there status.

Returns

0 if the thread should terminate.

Definition at line 143 of file thread.c.

References objunref(), testflag, thread_pvt::thr, and TL_THREAD_RUN.

                                {
    struct thread_pvt *thr;
    int ret;

    thr = get_thread_from_id();
    ret =(thr) ? testflag(thr, TL_THREAD_RUN) : 0;
    objunref(thr);

    return ret;
}

void jointhreads

(

void

)

Join the manager thread.

This will be done when you have issued stopthreads and are waiting or have completed the program and want to let the threads continue. for threads to exit.

Definition at line 450 of file thread.c.

References threadcontainer::manager, objlock(), objref(), objunlock(), objunref(), setflag, thread_pvt::thr, and TL_THREAD_JOIN.

                              {
    struct threadcontainer *tc;

    tc = (objref(threads)) ? threads : NULL;
    if (!tc) {
        return;
    }

    objlock(tc);
    if (tc->manager) {
        setflag(tc->manager, TL_THREAD_JOIN);
        objunlock(tc);
        pthread_join(tc->manager->thr, NULL);
    } else {
        objunlock(tc);
    }
    objunref(tc);
}

int startthreads

(

void

)

Initialise the threadlist and start manager thread.

Note

There is no need to call this as it will start when first thread starts.

Returns

1 On success 0 on failure.

Definition at line 268 of file thread.c.

References create_bucketlist(), framework_mkthread(), threadcontainer::list, threadcontainer::manager, objalloc(), objref(), objunref(), THREAD_OPTION_JOINABLE, and THREAD_OPTION_RETURN.

Referenced by framework_mkthread().

                              {
    struct threadcontainer *tc;

    tc = (objref(threads)) ? threads : NULL;

    if (tc) {
        objunref(tc);
        return 1;
    }

    if (!(tc = objalloc(sizeof(*threads), close_threads))) {
        return 0;
    }

    if (!tc->list && !(tc->list = create_bucketlist(4, hash_thread))) {
        objunref(tc);
        return 0;
    }

    threads = tc;
    if (!(tc->manager = framework_mkthread(managethread, manage_clean, manager_sig, NULL, THREAD_OPTION_JOINABLE | THREAD_OPTION_RETURN))) {
        objunref(tc);
        return 0;
    }

    return 1;
}

void stopthreads

(

int

join

)

Signal manager to stop and cancel all running threads.

This should always be called at shutdown if there have been threads started.

See Also

framework_init()

FRAMEWORK_MAIN()

Parameters

join	A non zero value to join the manager thread after flaging the shutdown.

Definition at line 303 of file thread.c.

References threadcontainer::manager, objlock(), objref(), objunlock(), objunref(), setflag, thread_pvt::thr, TL_THREAD_JOIN, and TL_THREAD_STOP.

Referenced by framework_init().

                                  {
    struct threadcontainer *tc;

    tc = (objref(threads)) ? threads : NULL;
    if (!tc) {
        return;
    }

    objlock(tc);
    if (tc->manager) {
        setflag(tc->manager, TL_THREAD_STOP);
        if (join) {
            setflag(tc->manager, TL_THREAD_JOIN);
            objunlock(tc);
            pthread_join(tc->manager->thr, NULL);
        } else {
            objunlock(tc);
        }
    } else {
        objunlock(tc);
    }
    objunlock(tc);
    objunref(tc);
}

int thread_signal

(

int

sig

)

Handle signal if its for me.

find the thread the signal was delivered to if the signal was handled returns 1 if the thread could not be handled returns -1 returns 0 if no thread is found NB sending a signal to the current thread while threads is locked will cause a deadlock.

Warning

This is not to be called directly but by the installed system signal handler.

Note

This is not supported on Win32

Parameters

sig	Signal to pass.

Returns

1 on success -1 on error.

Definition at line 496 of file thread.c.

References objunref().

                                  {
    int ret = 0;
#ifndef __WIN32
    struct thread_pvt *thread = NULL;

    if (!(thread = get_thread_from_id())) {
        return 0;
    }

    switch(sig) {
        case SIGUSR1:
        case SIGUSR2:
        case SIGHUP:
        case SIGALRM:
            ret = handle_thread_signal(thread, sig);
            break;
        case SIGINT:
        case SIGTERM:
            ret = handle_thread_signal(thread, sig);
    }
    objunref(thread);
#endif
    return ret;
}

Variable Documentation

int thread_can_start = 1

Automatically start manager thread.

If threads have not been started and a thread is created the manager thread will be started. once threads have stoped this will be set to zero manually starting startthreads will be possible.

Definition at line 92 of file thread.c.

Referenced by framework_mkthread().

struct threadcontainer* threads = NULL

Thread control data.

Definition at line 86 of file thread.c.