thread.c File Reference

#include <string.h>
#include <signal.h>
#include <mupnp/util/log.h>
#include <mupnp/util/thread.h>
#include <mupnp/util/time.h>

Functions
static void	sig_handler (int sign)
static void	mupnp_thread_createkey (void)
mUpnpThread *	mupnp_thread_self (void)
	Get the mUpnpThread object for the currently executing thread.
static void *	posix_thread_proc (void *param)
mUpnpThread *	mupnp_thread_new (void)
	Create a new thread instance.
bool	mupnp_thread_delete (mUpnpThread *thread)
	Stop and destroy a thread, freeing all resources.
bool	mupnp_thread_start (mUpnpThread *thread)
	Start a thread's execution.
bool	mupnp_thread_stop (mUpnpThread *thread)
	Request a thread to stop execution.
bool	mupnp_thread_stop_with_cond (mUpnpThread *thread, mUpnpCond *cond)
bool	mupnp_thread_restart (mUpnpThread *thread)
bool	mupnp_thread_isrunnable (mUpnpThread *thread)
void	mupnp_thread_setaction (mUpnpThread *thread, MUPNP_THREAD_FUNC func)
void	mupnp_thread_setuserdata (mUpnpThread *thread, void *value)
void *	mupnp_thread_getuserdata (mUpnpThread *thread)

Variables
static pthread_key_t	mupnpThreadSelfRef
static pthread_once_t	mupnpThreadMykeycreated = PTHREAD_ONCE_INIT

Function Documentation

mupnp_thread_createkey()

static void mupnp_thread_createkey ( void )

static

mupnp_thread_delete()

bool mupnp_thread_delete

(

mUpnpThread *

thread

)

Stop and destroy a thread, freeing all resources.

Stops the thread if it is running and releases all associated resources. This function blocks until the thread has fully terminated.

The thread's action function should periodically check mupnp_thread_isrunnable() and exit when it returns false to ensure graceful shutdown.

Parameters

thread

The thread to destroy. May be NULL (no-op if NULL).

Return values

true	Successfully stopped and destroyed the thread
false	Failed to destroy (e.g., thread is NULL)

Note

After calling this function, the thread pointer is invalid.

Blocking behavior: This function blocks until the thread terminates. If the thread does not check mupnp_thread_isrunnable(), it may block indefinitely.

Thread-safe: Must not be called concurrently on the same thread.

Warning

Do not call this function from the thread's own action function; this will cause deadlock.

See also

mupnp_thread_new()

mupnp_thread_stop()

mupnp_thread_getuserdata()

void * mupnp_thread_getuserdata

(

mUpnpThread *

thread

)

Get the user data pointer

Parameters

thread

Thread from which to get the pointer

mupnp_thread_isrunnable()

bool mupnp_thread_isrunnable

(

mUpnpThread *

thread

)

Check if a thread has been started

Parameters

thread

Thread to check

mupnp_thread_new()

mUpnpThread * mupnp_thread_new

(

void

)

Create a new thread instance.

Allocates and initializes a platform-independent thread object. The thread is initially in a stopped state (not running).

Before starting the thread, you must:

1. Set an action function with mupnp_thread_setaction()
2. Optionally set user data with mupnp_thread_setuserdata()

Platform support:

• Linux/Unix: pthread (POSIX threads)
• Windows: CreateThread API
• ITRON, T-Engine, BTRON: platform-specific task APIs

Returns

A newly-created mUpnpThread on success, or NULL if thread creation fails (e.g., insufficient system resources).

Note

The returned thread must be freed with mupnp_thread_delete() when no longer needed.

Thread-safe: Can be called concurrently from multiple threads.

The thread does not start automatically; call mupnp_thread_start() to begin execution.

See also

mupnp_thread_delete()

mupnp_thread_start()

mupnp_thread_setaction()

// Example: Create and start a worker thread
void worker_function(mUpnpThread* thread) {
    while (mupnp_thread_isrunnable(thread)) {
        // Perform work...
        mupnp_sleep(100);
    }
}
 
mUpnpThread* thread = mupnp_thread_new();
mupnp_thread_setaction(thread, worker_function);
mupnp_thread_start(thread);

mupnp_thread_restart()

bool mupnp_thread_restart

(

mUpnpThread *

thread

)

Restart a thread. Essentially calls mupnp_thread_stop() and mupnp_thread_start()

Parameters

thread

Thread to restart

mupnp_thread_self()

mUpnpThread * mupnp_thread_self

(

void

)

Get the mUpnpThread object for the currently executing thread.

Returns a reference to the thread structure for the calling thread. This is useful when a thread needs to access its own thread data or check if it should continue running.

Returns

Pointer to the current thread's mUpnpThread structure, or NULL if the calling thread was not created with mupnp_thread_new().

Note

Thread-safe: Can be called from any thread.

This function only works for threads created by the mUPnP library; external threads (e.g., main thread, OS threads) will return NULL.

See also

mupnp_thread_isrunnable()

mupnp_thread_setaction()

void mupnp_thread_setaction	(	mUpnpThread *	thread,
		MUPNP_THREAD_FUNC	actionFunc )

Set the thread's worker function.

Parameters

thread	Thread struct
actionFunc	Function pointer to set as the worker function

mupnp_thread_setuserdata()

void mupnp_thread_setuserdata	(	mUpnpThread *	thread,
		void *	data )

Set the user data pointer

Parameters

thread	Thread struct
data	Pointer to user data

mupnp_thread_start()

bool mupnp_thread_start

(

mUpnpThread *

thread

)

Start a thread's execution.

Starts the thread, causing its action function to begin execution in a new thread of control. The thread must have been created with mupnp_thread_new() and must have an action function set with mupnp_thread_setaction().

After starting, the action function runs concurrently with the calling thread until the thread is stopped or the action function returns.

Parameters

thread

The thread to start. Must not be NULL and must have an action function set.

Return values

true	Successfully started the thread
false	Failed to start due to: thread is NULL No action function set Thread already running System error (e.g., cannot create OS thread)

Note

Thread-safe: Can be called from any thread.

Calling this function on an already-running thread has no effect and returns false.

Side effect: Sets the thread's runnable flag to true and creates a new OS-level thread.

See also

mupnp_thread_stop()

mupnp_thread_isrunnable()

mupnp_thread_setaction()

mupnp_thread_stop()

bool mupnp_thread_stop

(

mUpnpThread *

thread

)

Request a thread to stop execution.

Signals the thread to stop by setting its runnable flag to false. This function does NOT forcibly terminate the thread; the thread's action function must cooperatively check mupnp_thread_isrunnable() and exit when it returns false.

This function returns immediately without waiting for the thread to terminate. Use mupnp_thread_delete() if you need to wait for termination.

Parameters

thread

The thread to stop. Must not be NULL.

Return values

true	Successfully signaled the thread to stop
false	Failed to signal (e.g., thread is NULL)

Note

Non-blocking: Returns immediately without waiting for thread exit.

Thread-safe: Can be called from any thread, including the thread being stopped.

Side effect: Sets the thread's runnable flag to false.

The thread continues running until its action function checks mupnp_thread_isrunnable() and exits.

See also

mupnp_thread_start()

mupnp_thread_isrunnable()

mupnp_thread_delete()

mupnp_thread_stop_with_cond()

bool mupnp_thread_stop_with_cond	(	mUpnpThread *	thread,
		mUpnpCond *	cond )

Stop the running thread and signal the given CGCond.

posix_thread_proc()

static void * posix_thread_proc ( void * param )

static

sig_handler()

static void sig_handler ( int sign )

static

Variable Documentation

mupnpThreadMykeycreated

pthread_once_t mupnpThreadMykeycreated = PTHREAD_ONCE_INIT

static

mupnpThreadSelfRef

pthread_key_t mupnpThreadSelfRef

static