Thread information

Description

These functions can be used to obtain some basic information about various threads in the system. Typically they serve little or no purpose in real applications, but they can be useful during debugging.

cyg_thread_self returns a handle corresponding to the current thread. It will be the same as the value filled in by cyg_thread_create when the current thread was created. This handle can then be passed to other functions such as cyg_thread_get_priority.

cyg_thread_idle_thread returns the handle corresponding to the idle thread. This thread is created automatically by the kernel, so application-code has no other way of getting hold of this information.

cyg_thread_get_stack_base and cyg_thread_get_stack_size return information about a specific thread's stack. The values returned will match the values passed to cyg_thread_create when this thread was created.

cyg_thread_measure_stack_usage is only available if the configuration option CYGFUN_KERNEL_THREADS_STACK_MEASUREMENT is enabled. The return value is the maximum number of bytes of stack space used so far by the specified thread. Note that this should not be considered a true upper bound, for example it is possible that in the current test run the specified thread has not yet been interrupted at the deepest point in the function call graph. Never the less the value returned can give some useful indication of the thread's stack requirements.

cyg_thread_get_next is used to enumerate all the current threads in the system. It should be called initially with the locations pointed to by thread and id set to zero. On return these will be set to the handle and ID of the first thread. On subsequent calls, these parameters should be left set to the values returned by the previous call. The handle and ID of the next thread in the system will be installed each time, until a false return value indicates the end of the list.

cyg_thread_get_info fills in the cyg_thread_info structure with information about the thread described by the thread and id arguments. The information returned includes the thread's handle and id, its state and name, priorities and stack parameters. If the thread does not exist the function returns false.

The cyg_thread_info structure is defined as follows by <cyg/kernel/kapi.h>, but may be extended in future with additional members, and so its size should not be relied upon:

typedef struct
{
    cyg_handle_t        handle;
    cyg_uint16          id;
    cyg_uint32          state;
    char                *name;
    cyg_priority_t      set_pri;
    cyg_priority_t      cur_pri;
    cyg_addrword_t      stack_base;
    cyg_uint32          stack_size;
    cyg_uint32          stack_used;
} cyg_thread_info;

cyg_thread_get_id returns the unique thread ID for the thread identified by thread.

cyg_thread_find returns a handle for the thread whose ID is id. If no such thread exists, a zero handle is returned.

Valid contexts

cyg_thread_self may only be called from thread context. cyg_thread_idle_thread may be called from thread or DSR context, but only after the system has been initialized. cyg_thread_get_stack_base, cyg_thread_get_stack_size and cyg_thread_measure_stack_usage may be called any time after the specified thread has been created, but measuring stack usage involves looping over at least part of the thread's stack so this should normally only be done from thread context. cyg_thread_get_id may be called from any context as long as the caller can guarantee that the supplied thread handle remains valid.

Examples

A simple example of the use of the cyg_thread_get_next and cyg_thread_get_info follows:

#include <cyg/kernel/kapi.h>
#include <stdio.h>

void show_threads(void)
{
    cyg_handle_t thread = 0;
    cyg_uint16 id = 0;

    while( cyg_thread_get_next( &thread, &id ) )
    {
        cyg_thread_info info;

        if( !cyg_thread_get_info( thread, id, &info ) )
            break;

        printf("ID: %04x name: %10s pri: %d\n",
                info.id, info.name?info.name:"----", info.set_pri );
    }
}