RFC: k_thread_join()

[andrewboie]

Is your enhancement proposal related to a problem? Please describe.
There's no good way to block until another thread exits.

Our test cases currently manage this in a few ways:

1. Create an equal priority co-op thread, or higher priority thread, and then yield() the CPU, or sleep for a while. Assuming the child thread never blocks and then exits, control returns after yield() completes...if we are in uniprocessor. In SMP the child could spawn on another CPU in which case after the yield() returns the child is probably still running. The workaround is the 1cpu variant of test case declarations, which spawn a busy-looping co-op thread on all other CPUs.

2. Synchronize by having the parent take a semaphore given by the child at the end of its entry function. Potentially race-prone if the child hasn't completely exited and the parent tries to re-use the thread object, resulting in a crash, but still safer than zephyr-master_fork #1.

Waiting for a thread to exit is also a common API offered by OSes, with many use-cases (see pthread_join(), waitpid()).

Describe the solution you'd like

__syscall int k_thread_join(struct k_thread *thread, u32_t timeout);

Block until the target thread exits, either normally or because it was aborted.
Returns immediately if the thread isn't active.
Returns -ETIMEDOUT if the timeout expires.
Not sure if we can handle thread objects that have never been initialized, although from user mode we can check the initialization bit. Calling this API on an uninitialized thread object is probably undefined behavior.
Return -EDEADLK if two threads try to join with each other, or a thread tries to join itself.
Treat multiple threads trying to join a single thread as undefined behavior, similar to pthread_join(), returning -EINVAL to one of the callers if this is detected.
Need an assertion to fail if someone calls this out of thread context.

Alternatively, we could implement something with semantics like waitpid() instead of pthread_join(), this would be workable for tests since AFAIK it's always a child thread we are waiting on.

With tests updated to use this API, a great many tests with SMP disabled or running in 1cpu test variant can work fine without these workarounds.

[mbolivar]

Seems reasonable. Just for completeness, can you document the semantics if called from outside thread context?

Are there any additional semantics that need documenting related to meta-irqs?

[andrewboie]

Seems reasonable. Just for completeness, can you document the semantics if called from outside thread context?

Are there any additional semantics that need documenting related to meta-irqs?

Sure. Since this is a blocking call, we'd need an assertion to fail if someone calls this out of thread context.

meta-irq threads can sleep so I think it is OK to call this from there, although a use-case for this API from meta-irqs currently escapes me.

[mbolivar]

Sure. Since this is a blocking call, we'd need an assertion to fail if someone calls this out of thread context.

Yep, seems reasonable, care to update the issue description to include that?

meta-irq threads can sleep so I think it is OK to call this from there, although a use-case for this API from meta-irqs currently escapes me.

Sounds good. And what about calling it on a meta-irq? No unusual edge cases there either?

[andrewboie]

And what about calling it on a meta-irq? No unusual edge cases there either?

Good call, @andyross any idea?

[carlescufi]

@andrewboie can we close this?