michaelh/zephyr
1
0
Fork 0
Code Releases Activity

kernel: Deprecate k_thread_cancel() API

Browse source 
The only difference between this call and k_thread_abort() (beyond
some minor performance deltas) is that "cancel" will act as a noop in
cases where the thread has begun execution and will return an error.
"Abort" always succeeds, of course.  That is inherently racy when used
as a "stop the thread" API: there's no way in general (or at all in
SMP situations) to know that you're calling this function "early
enough" to catch the thread before it starts.

Effectively, all k_thread_cancel() gives you that k_thread_abort()
doesn't is an indication about whether or not a thread has started.
There are many other ways to get that information that don't require
dangerous kernel APIs.

Deprecate this function.  Zephyr's own code never used it except for
its own unit test.

Signed-off-by: Andy Ross <andrew.j.ross@intel.com>
This commit is contained in:
Andy Ross 2018-04-03 09:42:40 -07:00 • committed by Anas Nashif
commit 3f55dafebc
4 changed files with 3 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

1
doc/kernel/threads/lifecycle.rst
View file

@ -289,7 +289,6 @@ The following thread APIs are provided by :file:`kernel.h`:
* :c:macro:`K_THREAD_DEFINE`
* :cpp:func:`k_thread_create()`
* :cpp:func:`k_thread_cancel()`
* :cpp:func:`k_thread_abort()`
* :cpp:func:`k_thread_suspend()`
* :cpp:func:`k_thread_resume()`

4
include/kernel.h
View file

@ -717,8 +717,10 @@ __syscall k_tid_t k_current_get(void);
*
* @retval 0 Thread spawning canceled.
* @retval -EINVAL Thread has already started executing.
*
* @deprecated This API is deprecated. Use k_thread_abort().
*/
__syscall int k_thread_cancel(k_tid_t thread);
__deprecated __syscall int k_thread_cancel(k_tid_t thread);
/**
* @brief Abort a thread.

6
tests/kernel/threads/lifecycle/lifecycle_api/src/main.c
View file

@ -20,9 +20,6 @@ extern void test_threads_spawn_forever(void);
extern void test_thread_start(void);
extern void test_threads_suspend_resume_cooperative(void);
extern void test_threads_suspend_resume_preemptible(void);
extern void test_threads_cancel_undelayed(void);
extern void test_threads_cancel_delayed(void);
extern void test_threads_cancel_started(void);
extern void test_threads_abort_self(void);
extern void test_threads_abort_others(void);
extern void test_threads_abort_repeat(void);
@ -52,9 +49,6 @@ void test_main(void)
ztest_unit_test(test_threads_suspend_resume_cooperative),
ztest_unit_test(test_threads_suspend_resume_preemptible),
ztest_unit_test(test_threads_priority_set),
ztest_user_unit_test(test_threads_cancel_undelayed),
ztest_user_unit_test(test_threads_cancel_delayed),
ztest_user_unit_test(test_threads_cancel_started),
ztest_user_unit_test(test_threads_abort_self),
ztest_user_unit_test(test_threads_abort_others),
ztest_unit_test(test_threads_abort_repeat),

57
tests/kernel/threads/lifecycle/lifecycle_api/src/test_threads_cancel_abort.c
View file

@ -37,63 +37,6 @@ static void thread_entry_abort(void *p1, void *p2, void *p3)
zassert_true(1 == 0, NULL);
}
/*test cases*/
void test_threads_cancel_undelayed(void)
{
int cur_prio = k_thread_priority_get(k_current_get());
/* spawn thread with lower priority */
int spawn_prio = cur_prio + 1;
k_tid_t tid = k_thread_create(&tdata, tstack, STACK_SIZE,
thread_entry, NULL, NULL, NULL,
spawn_prio, K_USER, 0);
/**TESTPOINT: check cancel retcode when thread is not delayed*/
int cancel_ret = k_thread_cancel(tid);
zassert_equal(cancel_ret, -EINVAL, NULL);
k_thread_abort(tid);
}
void test_threads_cancel_started(void)
{
int cur_prio = k_thread_priority_get(k_current_get());
/* spawn thread with lower priority */
int spawn_prio = cur_prio + 1;
k_tid_t tid = k_thread_create(&tdata, tstack, STACK_SIZE,
thread_entry, NULL, NULL, NULL,
spawn_prio, K_USER, 0);
k_sleep(50);
/**TESTPOINT: check cancel retcode when thread is started*/
int cancel_ret = k_thread_cancel(tid);
zassert_equal(cancel_ret, -EINVAL, NULL);
k_thread_abort(tid);
}
void test_threads_cancel_delayed(void)
{
int cur_prio = k_thread_priority_get(k_current_get());
/* spawn thread with lower priority */
int spawn_prio = cur_prio + 1;
k_tid_t tid = k_thread_create(&tdata, tstack, STACK_SIZE,
thread_entry, NULL, NULL, NULL,
spawn_prio, K_USER, 100);
k_sleep(50);
/**TESTPOINT: check cancel retcode when thread is started*/
int cancel_ret = k_thread_cancel(tid);
zassert_equal(cancel_ret, 0, NULL);
k_thread_abort(tid);
}
void test_threads_abort_self(void)
{
execute_flag = 0;