1#ifndef AWS_COMMON_THREAD_H
2#define AWS_COMMON_THREAD_H
3
4/*
5 * Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
6 *
7 * Licensed under the Apache License, Version 2.0 (the "License").
8 * You may not use this file except in compliance with the License.
9 * A copy of the License is located at
10 *
11 * http://aws.amazon.com/apache2.0
12 *
13 * or in the "license" file accompanying this file. This file is distributed
14 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
15 * express or implied. See the License for the specific language governing
16 * permissions and limitations under the License.
17 */
18#include <aws/common/common.h>
19
20#ifndef _WIN32
21# include <pthread.h>
22#endif
23
24enum aws_thread_detach_state {
25 AWS_THREAD_NOT_CREATED = 1,
26 AWS_THREAD_JOINABLE,
27 AWS_THREAD_JOIN_COMPLETED,
28};
29
30struct aws_thread_options {
31 size_t stack_size;
32};
33
34#ifdef _WIN32
35typedef union {
36 void *ptr;
37} aws_thread_once;
38# define AWS_THREAD_ONCE_STATIC_INIT \
39 { NULL }
40#else
41typedef pthread_once_t aws_thread_once;
42# define AWS_THREAD_ONCE_STATIC_INIT PTHREAD_ONCE_INIT
43#endif
44
45struct aws_thread {
46 struct aws_allocator *allocator;
47 enum aws_thread_detach_state detach_state;
48#ifdef _WIN32
49 void *thread_handle;
50 unsigned long thread_id;
51#else
52 pthread_t thread_id;
53#endif
54};
55
56AWS_EXTERN_C_BEGIN
57
58/**
59 * Returns an instance of system default thread options.
60 */
61AWS_COMMON_API
62const struct aws_thread_options *aws_default_thread_options(void);
63
64AWS_COMMON_API void aws_thread_call_once(aws_thread_once *flag, void (*call_once)(void *), void *user_data);
65
66/**
67 * Initializes a new platform specific thread object struct (not the os-level
68 * thread itself).
69 */
70AWS_COMMON_API
71int aws_thread_init(struct aws_thread *thread, struct aws_allocator *allocator);
72
73/**
74 * Creates an OS level thread and associates it with func. context will be passed to func when it is executed.
75 * options will be applied to the thread if they are applicable for the platform.
76 * You must either call join or detach after creating the thread and before calling clean_up.
77 */
78AWS_COMMON_API
79int aws_thread_launch(
80 struct aws_thread *thread,
81 void (*func)(void *arg),
82 void *arg,
83 const struct aws_thread_options *options);
84
85/**
86 * Gets the id of thread
87 */
88AWS_COMMON_API
89uint64_t aws_thread_get_id(struct aws_thread *thread);
90
91/**
92 * Gets the detach state of the thread. For example, is it safe to call join on
93 * this thread? Has it been detached()?
94 */
95AWS_COMMON_API
96enum aws_thread_detach_state aws_thread_get_detach_state(struct aws_thread *thread);
97
98/**
99 * Joins the calling thread to a thread instance. Returns when thread is
100 * finished.
101 */
102AWS_COMMON_API
103int aws_thread_join(struct aws_thread *thread);
104
105/**
106 * Cleans up the thread handle. Either detach or join must be called
107 * before calling this function.
108 */
109AWS_COMMON_API
110void aws_thread_clean_up(struct aws_thread *thread);
111
112/**
113 * returns the thread id of the calling thread.
114 */
115AWS_COMMON_API
116uint64_t aws_thread_current_thread_id(void);
117
118/**
119 * Sleeps the current thread by nanos.
120 */
121AWS_COMMON_API
122void aws_thread_current_sleep(uint64_t nanos);
123
124typedef void(aws_thread_atexit_fn)(void *user_data);
125
126/**
127 * Adds a callback to the chain to be called when the current thread joins.
128 * Callbacks are called from the current thread, in the reverse order they
129 * were added, after the thread function returns.
130 * If not called from within an aws_thread, has no effect.
131 */
132AWS_COMMON_API
133int aws_thread_current_at_exit(aws_thread_atexit_fn *callback, void *user_data);
134
135AWS_EXTERN_C_END
136
137#endif /* AWS_COMMON_THREAD_H */
138