eCos Reference Manual
Prev |  | Next

# Thread information

## Name

cyg_thread_self, cyg_thread_idle_thread, cyg_thread_get_stack_base, cyg_thread_get_stack_size, cyg_thread_measure_stack_usage, cyg_thread_get_next, cyg_thread_get_info, cyg_thread_get_id, cyg_thread_find -- Get basic thread information

## Synopsis

    #include <cyg/kernel/kapi.h>

``cyg_handle_t cyg_thread_self`(void);`

``cyg_handle_t cyg_thread_idle_thread`(void);`

``cyg_addrword_t cyg_thread_get_stack_base`(cyg_handle_t thread);`

``cyg_uint32 cyg_thread_get_stack_size`(cyg_handle_t thread);`

``cyg_uint32 cyg_thread_measure_stack_usage`(cyg_handle_t thread);`

``cyg_bool cyg_thread_get_next`(cyg_handle_t *thread, cyg_uint16 *id);`

``cyg_bool cyg_thread_get_info`(cyg_handle_t thread, cyg_uint16 id, cyg_thread_info *info);`

``cyg_uint16 cyg_thread_get_id`(cyg_handle_t thread);`

``cyg_handle_t cyg_thread_find`(cyg_uint16 id);`

## 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 );
        }
    }

Prev | Home | Next
Thread creation | Up | Thread control