Re: [PATCH] Add thread local storage to libthread documentation.

[Ori Bernstein <ori@xxxxxxxxxxxxxx>]

Merged. Thanks!

On Thu, 06 Dec 2018 22:52:16 -0800, iriri <iri@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx> wrote:

> 
> ---
>  doc/libthread/index.txt | 75 +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 75 insertions(+)
> 
> diff --git a/doc/libthread/index.txt b/doc/libthread/index.txt
> index f9f4593..1bfc0f5 100644
> --- a/doc/libthread/index.txt
> +++ b/doc/libthread/index.txt
> @@ -39,6 +39,8 @@ Summary
>  			...
>  		;;
>  
> +		type tlskey(@a#)
> +
>  		impl atomic int32
>  		impl atomic int64
>  		impl atomic uint32
> @@ -85,8 +87,14 @@ Summary
>  		generic xcasptr : (p : @a##, old : std.option(@a#), new : std.option(@a#) -> std.option(@a#))
>  		generic xchgptr : (p : @a##, new : std.option(@a#) -> std.option(@a#))
>  
> +		/* thread local storage */
> +		generic tlsalloc : (-> tlskey(@a#))
> +		generic tlsset   : (k : tlskey(@a#), v : @a# -> void)
> +		generic tlsget   : (k : tlskey(@a#) -> @a#)
> +
>  		/* misc */
>  		const ncpu	: (-> int)
> +		const tid	: (-> tid)
>  	;;
>  
>  Types
> @@ -280,6 +288,68 @@ These are identical to the corresponding atomic implementations for integral
>  types except `std.Some v` is used to represent a nonzero pointer and `std.None`
>  is used to represent the zero pointer.
>  
> +Thread Local Storage
> +--------------------
> +
> +Thread local storage can be used in cases where different threads each need
> +their own copy of the same global variable. These variables must be pointers
> +and are accessed via shared keys. The thread local variables of a newly spawned
> +thread are uninitialized.
> +
> +	generic tlsalloc : (-> tlskey(@a#))
> +
> +Allocates a new thread local variable and returns its key.
> +
> +This function must be called from the main thread. The thread local variables
> +available to a child thread C are the thread local variables available to its
> +parent P at the time when P spawned C.
> +
> +	generic tlsset   : (k : tlskey(@a#), v : @a# -> void)
> +
> +Sets the thread local variable associated with the given key.
> +
> +	generic tlsget   : (k : tlskey(@a#) -> @a#)
> +
> +Gets the thread local variable associated with the given key.
> +
> +In the following example, a thread local variable is allocated and each thread
> +stores a tuple of its id and the current time. A wait group is then used to
> +serialize the printing of these values, demonstrating that each thread has a
> +unique copy of the variable.
> +
> +```{runmyr threadlocal}
> +use std
> +use thread
> +
> +var key
> +var wg
> +
> +const set = {
> +	var t = std.mk((thread.tid(), std.now()))
> +	thread.tlsset(key, t)
> +}
> +
> +const greet = {
> +	var t = thread.tlsget(key)
> +	std.put("hello from thread {w=5} at time {}\n", t#.0, t#.1 % 1000000)
> +	std.free(t)
> +}
> +
> +const main = {
> +	key = thread.tlsalloc()
> +	wg = thread.mkwg(1)
> +
> +	set()
> +	thread.spawn({
> +		set()
> +		greet()
> +		thread.wgpost(&wg)
> +	})
> +	thread.wgwait(&wg)
> +	greet()
> +}
> +```
> +
>  Misc
>  ----
>  
> @@ -287,3 +357,8 @@ Misc
>  
>  Returns the number of CPUs available to run your code. On systems where this
>  information is unavailable, `1` is returned as a safe default.
> +
> +	const tid : (-> tid)
> +
> +Returns the thread id of the current thread. The main thread is guaranteed to
> +have thread id 0.
> -- 
> 2.19.2
> 
> 


-- 
    Ori Bernstein