Skip to content

Commit e3b5603

Browse files
Ewout van BekkumCQ Bot Account
Ewout van Bekkum
authored and
CQ Bot Account
committedJan 28, 2021
pw_thread: adds the initial pw_thread module
Adds a std::this_thread like API through the pw_thread facades, that is: 1) this_thread::yield 2) this_thread::sleep_{for,until} 3) this_thread::get_id This module is split into many different facades in order to let users decide what functionality they want to use as they may not always be available, for example when using opaque SDKs. In addition this provides an initial set of backends based on using the STL's std::this_thread directly and selects them for the host target. Change-Id: I0ee8e4390ba988b2b13e9ee59f976f2333715f1f Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/30040 Commit-Queue: Ewout van Bekkum <ewout@google.com> Reviewed-by: Keir Mierle <keir@google.com> Reviewed-by: Wyatt Hepler <hepler@google.com>
1 parent 49a4a82 commit e3b5603

28 files changed

+1031
-0
lines changed
 

‎BUILD.gn

+2
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,7 @@ if (current_toolchain != default_toolchain) {
234234
"$dir_pw_string",
235235
"$dir_pw_sync",
236236
"$dir_pw_sys_io",
237+
"$dir_pw_thread",
237238
"$dir_pw_trace",
238239
"$dir_pw_unit_test",
239240
"$dir_pw_varint",
@@ -288,6 +289,7 @@ if (current_toolchain != default_toolchain) {
288289
"$dir_pw_stream:tests",
289290
"$dir_pw_string:tests",
290291
"$dir_pw_sync:tests",
292+
"$dir_pw_thread:tests",
291293
"$dir_pw_tokenizer:tests",
292294
"$dir_pw_trace:tests",
293295
"$dir_pw_trace_tokenized:tests",

‎modules.gni

+2
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,8 @@ declare_args() {
9090
dir_pw_sys_io_arduino = get_path_info("pw_sys_io_arduino", "abspath")
9191
dir_pw_sys_io_stdio = get_path_info("pw_sys_io_stdio", "abspath")
9292
dir_pw_target_runner = get_path_info("pw_target_runner", "abspath")
93+
dir_pw_thread = get_path_info("pw_thread", "abspath")
94+
dir_pw_thread_stl = get_path_info("pw_thread_stl", "abspath")
9395
dir_pw_third_party = get_path_info("third_party", "abspath")
9496
dir_pw_tokenizer = get_path_info("pw_tokenizer", "abspath")
9597
dir_pw_toolchain = get_path_info("pw_toolchain", "abspath")

‎pw_thread/BUILD

+153
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Copyright 2020 The Pigweed Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
# use this file except in compliance with the License. You may obtain a copy of
5+
# the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
# License for the specific language governing permissions and limitations under
13+
# the License.
14+
15+
load(
16+
"//pw_build:pigweed.bzl",
17+
"pw_cc_library",
18+
"pw_cc_test",
19+
)
20+
21+
package(default_visibility = ["//visibility:public"])
22+
23+
licenses(["notice"]) # Apache License 2.0
24+
25+
# TODO(pwbug/101): Need to add support for facades/backends to Bazel.
26+
PW_THREAD_ID_BACKEND = "//pw_thread_stl:id"
27+
PW_THREAD_SLEEP_BACKEND = "//pw_thread_stl:sleep"
28+
PW_THREAD_YIELD_BACKEND = "//pw_thread_stl:yield"
29+
30+
pw_cc_library(
31+
name = "id_facade",
32+
hdrs = [
33+
"public/pw_thread/id.h",
34+
],
35+
includes = ["public"],
36+
deps = [
37+
PW_THREAD_ID_BACKEND + "_headers",
38+
],
39+
)
40+
41+
pw_cc_library(
42+
name = "id",
43+
deps = [
44+
":id_facade",
45+
PW_THREAD_ID_BACKEND + "_headers",
46+
],
47+
)
48+
49+
pw_cc_library(
50+
name = "id_backend",
51+
deps = [
52+
PW_THREAD_ID_BACKEND,
53+
],
54+
)
55+
56+
pw_cc_library(
57+
name = "sleep_facade",
58+
hdrs = [
59+
"public/pw_thread/sleep.h",
60+
],
61+
includes = ["public"],
62+
srcs = [
63+
"sleep.cc"
64+
],
65+
deps = [
66+
PW_THREAD_SLEEP_BACKEND + "_headers",
67+
"//pw_chrono:system_clock",
68+
"//pw_preprocessor",
69+
],
70+
)
71+
72+
pw_cc_library(
73+
name = "sleep",
74+
deps = [
75+
":sleep_facade",
76+
PW_THREAD_SLEEP_BACKEND + "_headers",
77+
],
78+
)
79+
80+
pw_cc_library(
81+
name = "sleep_backend",
82+
deps = [
83+
PW_THREAD_SLEEP_BACKEND,
84+
],
85+
)
86+
87+
pw_cc_library(
88+
name = "yield_facade",
89+
hdrs = [
90+
"public/pw_thread/yield.h",
91+
],
92+
includes = ["public"],
93+
srcs = [
94+
"yield.cc"
95+
],
96+
deps = [
97+
PW_THREAD_YIELD_BACKEND + "_headers",
98+
"//pw_preprocessor",
99+
],
100+
)
101+
102+
pw_cc_library(
103+
name = "yield",
104+
deps = [
105+
":yield_facade",
106+
PW_THREAD_YIELD_BACKEND + "_headers",
107+
],
108+
)
109+
110+
pw_cc_library(
111+
name = "yield_backend",
112+
deps = [
113+
PW_THREAD_YIELD_BACKEND,
114+
],
115+
)
116+
117+
pw_cc_test(
118+
name = "id_facade_test",
119+
srcs = [
120+
"id_facade_test.cc",
121+
],
122+
deps = [
123+
":id",
124+
"//pw_unit_test",
125+
],
126+
)
127+
128+
pw_cc_test(
129+
name = "sleep_facade_test",
130+
srcs = [
131+
"sleep_facade_test.cc",
132+
"sleep_facade_test_c.c",
133+
],
134+
deps = [
135+
":sleep",
136+
"//pw_chrono:system_clock",
137+
"//pw_preprocessor",
138+
"//pw_unit_test",
139+
],
140+
)
141+
142+
pw_cc_test(
143+
name = "yield_facade_test",
144+
srcs = [
145+
"yield_facade_test.cc",
146+
"yield_facade_test_c.c",
147+
],
148+
deps = [
149+
":yield",
150+
"//pw_preprocessor",
151+
"//pw_unit_test",
152+
],
153+
)

‎pw_thread/BUILD.gn

+94
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Copyright 2020 The Pigweed Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
# use this file except in compliance with the License. You may obtain a copy of
5+
# the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
# License for the specific language governing permissions and limitations under
13+
# the License.
14+
15+
import("//build_overrides/pigweed.gni")
16+
17+
import("$dir_pw_build/facade.gni")
18+
import("$dir_pw_build/target_types.gni")
19+
import("$dir_pw_docgen/docs.gni")
20+
import("$dir_pw_unit_test/test.gni")
21+
import("backend.gni")
22+
23+
config("public_include_path") {
24+
include_dirs = [ "public" ]
25+
visibility = [ ":*" ]
26+
}
27+
28+
pw_facade("id") {
29+
backend = pw_thread_ID_BACKEND
30+
public_configs = [ ":public_include_path" ]
31+
public = [ "public/pw_thread/id.h" ]
32+
}
33+
34+
pw_facade("sleep") {
35+
backend = pw_thread_SLEEP_BACKEND
36+
public_configs = [ ":public_include_path" ]
37+
public = [ "public/pw_thread/sleep.h" ]
38+
public_deps = [
39+
"$dir_pw_chrono:system_clock",
40+
"$dir_pw_preprocessor",
41+
]
42+
sources = [ "sleep.cc" ]
43+
}
44+
45+
pw_facade("yield") {
46+
backend = pw_thread_YIELD_BACKEND
47+
public_configs = [ ":public_include_path" ]
48+
public = [ "public/pw_thread/yield.h" ]
49+
public_deps = [ "$dir_pw_preprocessor" ]
50+
sources = [ "yield.cc" ]
51+
}
52+
53+
pw_test_group("tests") {
54+
tests = [
55+
":id_facade_test",
56+
":sleep_facade_test",
57+
":yield_facade_test",
58+
]
59+
}
60+
61+
pw_test("id_facade_test") {
62+
enable_if = pw_thread_ID_BACKEND != ""
63+
sources = [ "id_facade_test.cc" ]
64+
deps = [ ":id" ]
65+
}
66+
67+
pw_test("sleep_facade_test") {
68+
enable_if = pw_thread_SLEEP_BACKEND != "" && pw_thread_ID_BACKEND != ""
69+
sources = [
70+
"sleep_facade_test.cc",
71+
"sleep_facade_test_c.c",
72+
]
73+
deps = [
74+
":id",
75+
":sleep",
76+
"$dir_pw_chrono:system_clock",
77+
]
78+
}
79+
80+
pw_test("yield_facade_test") {
81+
enable_if = pw_thread_YIELD_BACKEND != "" && pw_thread_ID_BACKEND != ""
82+
sources = [
83+
"yield_facade_test.cc",
84+
"yield_facade_test_c.c",
85+
]
86+
deps = [
87+
":id",
88+
":yield",
89+
]
90+
}
91+
92+
pw_doc_group("docs") {
93+
sources = [ "docs.rst" ]
94+
}

‎pw_thread/backend.gni

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Copyright 2020 The Pigweed Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
# use this file except in compliance with the License. You may obtain a copy of
5+
# the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
# License for the specific language governing permissions and limitations under
13+
# the License.
14+
15+
declare_args() {
16+
# Backend for the pw_thread module's pw::thread::Id.
17+
pw_thread_ID_BACKEND = ""
18+
19+
# Backend for the pw_thread module's pw::thread::sleep_{for,until}.
20+
pw_thread_SLEEP_BACKEND = ""
21+
22+
# Backend for the pw_thread module's pw::thread::yield.
23+
pw_thread_YIELD_BACKEND = ""
24+
}

‎pw_thread/docs.rst

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. _module-pw_thread:
2+
3+
---------
4+
pw_thread
5+
---------
6+
This is a threading module for Pigweed. It is not ready for use, and is under
7+
construction.
8+

‎pw_thread/id_facade_test.cc

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
15+
#include "gtest/gtest.h"
16+
#include "pw_thread/id.h"
17+
18+
namespace pw::this_thread {
19+
namespace {
20+
21+
TEST(Id, GetId) {
22+
// We expect unit tests to run in a thread context.
23+
// Unfortunately beyond this we need the ability to create and destroy threads
24+
// to test more Id functionality.
25+
EXPECT_NE(get_id(), thread::Id());
26+
}
27+
28+
} // namespace
29+
} // namespace pw::this_thread

‎pw_thread/public/pw_thread/id.h

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
#pragma once
15+
16+
#include "pw_thread_backend/id_native.h"
17+
18+
namespace pw::thread {
19+
20+
// The class thread::id is a lightweight, trivially copyable class that serves
21+
// as a unique identifier of Thread objects.
22+
//
23+
// Instances of this class may also hold the special distinct value that does
24+
// not represent any thread. Once a thread has finished, the value of
25+
// Thread::id may be reused by another thread.
26+
//
27+
// This class is designed for use as key in associative containers, both
28+
// ordered and unordered.
29+
//
30+
// The backend must ensure that:
31+
// 1) There is a default construct which does not represent a thread.
32+
// 2) Compare operators (==,!=,<,<=,>,>=) are provided to compare and sort IDs.
33+
using Id = backend::NativeId;
34+
35+
} // namespace pw::thread
36+
37+
namespace pw::this_thread {
38+
39+
// This is thread safe, not IRQ safe. It is implementation defined whether this
40+
// is safe before the scheduler has started.
41+
thread::Id get_id() noexcept;
42+
43+
} // namespace pw::this_thread
44+
45+
// The backend can opt to include an inline implementation.
46+
#if __has_include("pw_thread_backend/id_inline.h")
47+
#include "pw_thread_backend/id_inline.h"
48+
#endif // __has_include("pw_thread_backend/id_inline.h")

‎pw_thread/public/pw_thread/sleep.h

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
#pragma once
15+
16+
#include "pw_chrono/system_clock.h"
17+
#include "pw_preprocessor/util.h"
18+
19+
#ifdef __cplusplus
20+
21+
namespace pw::this_thread {
22+
23+
// This can only be called from a thread, meaning the scheduler is running.
24+
void sleep_for(chrono::SystemClock::duration for_at_least);
25+
26+
// This can only be called from a thread, meaning the scheduler is running.
27+
void sleep_until(chrono::SystemClock::time_point until_at_least);
28+
29+
} // namespace pw::this_thread
30+
31+
// The backend can opt to include inlined implementations.
32+
#if __has_include("pw_thread_backend/sleep_inline.h")
33+
#include "pw_thread_backend/sleep_inline.h"
34+
#endif // __has_include("pw_thread_backend/sleep_inline.h")
35+
36+
#endif // __cplusplus
37+
38+
PW_EXTERN_C_START
39+
40+
void pw_this_thread_SleepFor(pw_chrono_SystemClock_TickCount for_at_least);
41+
void pw_this_thread_SleepUntil(pw_chrono_SystemClock_TimePoint until_at_least);
42+
43+
PW_EXTERN_C_END

‎pw_thread/public/pw_thread/yield.h

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
#pragma once
15+
16+
#include "pw_preprocessor/util.h"
17+
18+
#ifdef __cplusplus
19+
20+
namespace pw::this_thread {
21+
22+
// Provides a hint to the implementation to reschedule the execution of threads,
23+
// allowing other threads to run.
24+
//
25+
// The exact behavior of this function depends on the implementation, in
26+
// particular on the mechanics of the OS scheduler in use and the state of the
27+
// system.
28+
//
29+
// This can only be called from a thread, meaning the scheduler is running.
30+
void yield() noexcept;
31+
32+
} // namespace pw::this_thread
33+
34+
// The backend can opt to include an inline implementation.
35+
#if __has_include("pw_thread_backend/yield_inline.h")
36+
#include "pw_thread_backend/yield_inline.h"
37+
#endif // __has_include("pw_thread_backend/yield_inline.h")
38+
39+
#endif // __cplusplus
40+
41+
PW_EXTERN_C_START
42+
43+
void pw_this_thread_Yield(void);
44+
45+
PW_EXTERN_C_END

‎pw_thread/sleep.cc

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
15+
#include "pw_thread/sleep.h"
16+
17+
using pw::chrono::SystemClock;
18+
19+
extern "C" void pw_this_thread_SleepFor(
20+
pw_chrono_SystemClock_TickCount for_at_least) {
21+
pw::this_thread::sleep_for(SystemClock::duration(for_at_least));
22+
}
23+
24+
extern "C" void pw_this_thread_SleepUntil(
25+
pw_chrono_SystemClock_TimePoint until_at_least) {
26+
pw::this_thread::sleep_until(SystemClock::time_point(
27+
SystemClock::duration(until_at_least.ticks_since_epoch)));
28+
}

‎pw_thread/sleep_facade_test.cc

+89
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
15+
#include <chrono>
16+
17+
#include "gtest/gtest.h"
18+
#include "pw_chrono/system_clock.h"
19+
#include "pw_thread/id.h"
20+
#include "pw_thread/sleep.h"
21+
22+
using pw::chrono::SystemClock;
23+
24+
namespace pw::this_thread {
25+
namespace {
26+
27+
extern "C" {
28+
29+
// Functions defined in sleep_facade_test_c.c which call the API from C.
30+
void pw_this_thread_CallSleepFor(pw_chrono_SystemClock_TickCount for_at_least);
31+
void pw_this_thread_CallSleepUntil(
32+
pw_chrono_SystemClock_TimePoint until_at_least);
33+
34+
} // extern "C"
35+
36+
static constexpr auto kArbitraryDuration = std::chrono::milliseconds(42);
37+
// We can't control the SystemClock's period configuration, so just in case
38+
// duration cannot be accurately expressed in integer ticks, round the
39+
// duration w/ duration_cast.
40+
static constexpr auto kRoundedArbitraryDuration =
41+
std::chrono::duration_cast<SystemClock::duration>(kArbitraryDuration);
42+
static constexpr pw_chrono_SystemClock_TickCount kRoundedArbitraryDurationInC =
43+
kRoundedArbitraryDuration.count();
44+
45+
TEST(Sleep, SleepFor) {
46+
// Ensure we are in a thread context, meaning we are permitted to sleep.
47+
ASSERT_NE(get_id(), thread::Id());
48+
49+
const SystemClock::time_point before = SystemClock::now();
50+
sleep_for(kRoundedArbitraryDuration);
51+
const SystemClock::duration time_elapsed = SystemClock::now() - before;
52+
EXPECT_GE(time_elapsed, kRoundedArbitraryDuration);
53+
}
54+
55+
TEST(Sleep, SleepUntil) {
56+
// Ensure we are in a thread context, meaning we are permitted to sleep.
57+
ASSERT_NE(get_id(), thread::Id());
58+
59+
const SystemClock::time_point deadline =
60+
SystemClock::now() + kRoundedArbitraryDuration;
61+
sleep_until(deadline);
62+
EXPECT_GE(SystemClock::now(), deadline);
63+
}
64+
65+
TEST(Sleep, SleepForInC) {
66+
// Ensure we are in a thread context, meaning we are permitted to sleep.
67+
ASSERT_NE(get_id(), thread::Id());
68+
69+
pw_chrono_SystemClock_TimePoint before = pw_chrono_SystemClock_Now();
70+
pw_this_thread_SleepFor(kRoundedArbitraryDurationInC);
71+
pw_chrono_SystemClock_TickCount time_elapsed =
72+
pw_chrono_SystemClock_Now().ticks_since_epoch - before.ticks_since_epoch;
73+
EXPECT_GE(time_elapsed, kRoundedArbitraryDurationInC);
74+
}
75+
76+
TEST(Sleep, SleepUntilInC) {
77+
// Ensure we are in a thread context, meaning we are permitted to sleep.
78+
ASSERT_NE(get_id(), thread::Id());
79+
80+
pw_chrono_SystemClock_TimePoint deadline;
81+
deadline.ticks_since_epoch = pw_chrono_SystemClock_Now().ticks_since_epoch +
82+
kRoundedArbitraryDurationInC;
83+
pw_this_thread_CallSleepUntil(deadline);
84+
EXPECT_GE(pw_chrono_SystemClock_Now().ticks_since_epoch,
85+
deadline.ticks_since_epoch);
86+
}
87+
88+
} // namespace
89+
} // namespace pw::this_thread

‎pw_thread/sleep_facade_test_c.c

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
15+
// These tests call the pw_thread module sleep API from C. The return values are
16+
// checked in the main C++ tests.
17+
18+
#include "pw_thread/sleep.h"
19+
20+
void pw_this_thread_CallSleepFor(pw_chrono_SystemClock_TickCount for_at_least) {
21+
pw_this_thread_SleepFor(for_at_least);
22+
}
23+
24+
void pw_this_thread_CallSleepUntil(
25+
pw_chrono_SystemClock_TimePoint until_at_least) {
26+
pw_this_thread_SleepUntil(until_at_least);
27+
}

‎pw_thread/yield.cc

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
15+
#include "pw_thread/yield.h"
16+
17+
extern "C" void pw_this_thread_Yield() { pw::this_thread::yield(); }

‎pw_thread/yield_facade_test.cc

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
15+
#include "gtest/gtest.h"
16+
#include "pw_thread/id.h"
17+
#include "pw_thread/yield.h"
18+
19+
namespace pw::this_thread {
20+
namespace {
21+
22+
extern "C" {
23+
24+
// Function defined in yield_facade_test_c.c which call the API from C.
25+
void pw_this_thread_CallYield();
26+
27+
} // extern "C"
28+
29+
TEST(Yield, CompilesAndRuns) {
30+
// Ensure we are in a thread context, meaning we are permitted to sleep.
31+
ASSERT_NE(get_id(), thread::Id());
32+
33+
// Unfortunately we have not thought of a useful way to test yield without
34+
// knowing the backend implementation as things like round robin scheduling
35+
// may be enabled meaning it may appear like yield is working when it isn't.
36+
// For now we just ensure it compiles and we can execute it without a crash.
37+
yield();
38+
}
39+
40+
TEST(Yield, CompilesAndRunsInC) {
41+
// Ensure we are in a thread context, meaning we are permitted to sleep.
42+
ASSERT_NE(get_id(), thread::Id());
43+
44+
// Unfortunately we have not thought of a useful way to test yield without
45+
// knowing the backend implementation as things like round robin scheduling
46+
// may be enabled meaning it may appear like yield is working when it isn't.
47+
// For now we just ensure it compiles and we can execute it without a crash.
48+
pw_this_thread_CallYield();
49+
}
50+
51+
} // namespace
52+
} // namespace pw::this_thread

‎pw_thread/yield_facade_test_c.c

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
15+
// These tests call the pw_thread module yield API from C. The return values
16+
// are checked in the main C++ tests.
17+
18+
#include "pw_thread/yield.h"
19+
20+
void pw_this_thread_CallYield(void) { pw_this_thread_Yield(); }

‎pw_thread_stl/BUILD

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Copyright 2020 The Pigweed Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
# use this file except in compliance with the License. You may obtain a copy of
5+
# the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
# License for the specific language governing permissions and limitations under
13+
# the License.
14+
15+
load(
16+
"//pw_build:pigweed.bzl",
17+
"pw_cc_library",
18+
)
19+
20+
package(default_visibility = ["//visibility:public"])
21+
22+
licenses(["notice"]) # Apache License 2.0
23+
24+
pw_cc_library(
25+
name = "id_headers",
26+
hdrs = [
27+
"public/pw_thread_stl/id_inline.h",
28+
"public/pw_thread_stl/id_native.h",
29+
"public_overrides/pw_thread_backend/id_inline.h",
30+
"public_overrides/pw_thread_backend/id_native.h",
31+
],
32+
includes = [
33+
"public",
34+
"public_overrides",
35+
],
36+
)
37+
38+
pw_cc_library(
39+
name = "id",
40+
deps = [
41+
":id_headers",
42+
"//pw_thread:id_facade",
43+
],
44+
)
45+
46+
pw_cc_library(
47+
name = "sleep_headers",
48+
hdrs = [
49+
"public/pw_thread_stl/sleep_inline.h",
50+
"public_overrides/pw_thread_backend/sleep_inline.h",
51+
],
52+
includes = [
53+
"public",
54+
"public_overrides",
55+
],
56+
deps = [
57+
"//pw_chrono:system_clock",
58+
],
59+
)
60+
61+
pw_cc_library(
62+
name = "sleep",
63+
deps = [
64+
":sleep_headers",
65+
"//pw_chrono:system_clock",
66+
"//pw_thread:sleep_facade",
67+
],
68+
)
69+
70+
pw_cc_library(
71+
name = "yield_headers",
72+
hdrs = [
73+
"public/pw_thread_stl/yield_inline.h",
74+
"public_overrides/pw_thread_backend/yield_inline.h",
75+
],
76+
includes = [
77+
"public",
78+
"public_overrides",
79+
],
80+
)
81+
82+
pw_cc_library(
83+
name = "yield",
84+
deps = [
85+
":yield_headers",
86+
"//pw_thread:yield_facade",
87+
],
88+
)

‎pw_thread_stl/BUILD.gn

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Copyright 2020 The Pigweed Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
# use this file except in compliance with the License. You may obtain a copy of
5+
# the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
# License for the specific language governing permissions and limitations under
13+
# the License.
14+
15+
import("//build_overrides/pigweed.gni")
16+
17+
import("$dir_pw_build/target_types.gni")
18+
import("$dir_pw_chrono/backend.gni")
19+
import("$dir_pw_docgen/docs.gni")
20+
21+
config("public_include_path") {
22+
include_dirs = [ "public" ]
23+
visibility = [ ":*" ]
24+
}
25+
26+
config("backend_config") {
27+
include_dirs = [ "public_overrides" ]
28+
visibility = [ ":*" ]
29+
}
30+
31+
# This target provides the backend for pw::thread::Id & pw::this_thread::get_id.
32+
pw_source_set("id") {
33+
public_configs = [
34+
":public_include_path",
35+
":backend_config",
36+
]
37+
public = [
38+
"public/pw_thread_stl/id_inline.h",
39+
"public/pw_thread_stl/id_native.h",
40+
"public_overrides/pw_thread_backend/id_inline.h",
41+
"public_overrides/pw_thread_backend/id_native.h",
42+
]
43+
deps = [ "$dir_pw_thread:id.facade" ]
44+
}
45+
46+
# This target provides the backend for pw::this_thread::sleep_{for,until}.
47+
pw_source_set("sleep") {
48+
public_configs = [
49+
":public_include_path",
50+
":backend_config",
51+
]
52+
public = [
53+
"public/pw_thread_stl/sleep_inline.h",
54+
"public_overrides/pw_thread_backend/sleep_inline.h",
55+
]
56+
deps = [
57+
"$dir_pw_chrono:system_clock",
58+
"$dir_pw_thread:sleep.facade",
59+
]
60+
assert(
61+
pw_chrono_SYSTEM_CLOCK_BACKEND == "" ||
62+
pw_chrono_SYSTEM_CLOCK_BACKEND == "$dir_pw_chrono_stl:system_clock",
63+
"The STL pw::this_thread::sleep_{for,until} backend only works with " +
64+
"the STL pw::chrono::SystemClock backend " +
65+
"(pw_chrono_SYSTEM_CLOCK_BACKEND = " +
66+
"\"$dir_pw_chrono_stl:system_clock\")")
67+
}
68+
69+
# This target provides the backend for pw::this_thread::yield.
70+
pw_source_set("yield") {
71+
public_configs = [
72+
":public_include_path",
73+
":backend_config",
74+
]
75+
public = [
76+
"public/pw_thread_stl/yield_inline.h",
77+
"public_overrides/pw_thread_backend/yield_inline.h",
78+
]
79+
deps = [ "$dir_pw_thread:yield.facade" ]
80+
}
81+
82+
pw_doc_group("docs") {
83+
sources = [ "docs.rst" ]
84+
}

‎pw_thread_stl/docs.rst

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. _module-pw_thread_stl:
2+
3+
-------------
4+
pw_thread_stl
5+
-------------
6+
This is a set of backends for pw_thread based on the C++ STL. It is not ready
7+
for use, and is under construction.
8+

‎pw_thread_stl/public/pw_thread_stl/id_inline.h

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
#pragma once
15+
16+
#include <thread>
17+
18+
#include "pw_thread/id.h"
19+
20+
namespace pw::this_thread {
21+
22+
inline thread::Id get_id() noexcept { return std::this_thread::get_id(); }
23+
24+
} // namespace pw::this_thread

‎pw_thread_stl/public/pw_thread_stl/id_native.h

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
#pragma once
15+
16+
#include <thread>
17+
18+
namespace pw::thread::backend {
19+
20+
using NativeId = std::thread::id;
21+
22+
} // namespace pw::thread::backend

‎pw_thread_stl/public/pw_thread_stl/sleep_inline.h

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
#pragma once
15+
16+
#include <thread>
17+
18+
#include "pw_chrono/system_clock.h"
19+
#include "pw_thread/sleep.h"
20+
21+
namespace pw::this_thread {
22+
23+
inline void sleep_for(chrono::SystemClock::duration for_at_least) {
24+
return std::this_thread::sleep_for(for_at_least);
25+
}
26+
27+
inline void sleep_until(chrono::SystemClock::time_point until_at_least) {
28+
return std::this_thread::sleep_until(until_at_least);
29+
}
30+
31+
} // namespace pw::this_thread

‎pw_thread_stl/public/pw_thread_stl/yield_inline.h

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
#pragma once
15+
16+
#include <thread>
17+
18+
namespace pw::this_thread {
19+
20+
inline void yield() noexcept { std::this_thread::yield(); }
21+
22+
} // namespace pw::this_thread

‎pw_thread_stl/public_overrides/pw_thread_backend/id_inline.h

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
#pragma once
15+
16+
#include "pw_thread_stl/id_inline.h"

‎pw_thread_stl/public_overrides/pw_thread_backend/id_native.h

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
#pragma once
15+
16+
#include "pw_thread_stl/id_native.h"

‎pw_thread_stl/public_overrides/pw_thread_backend/sleep_inline.h

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
#pragma once
15+
16+
#include "pw_thread_stl/sleep_inline.h"

‎pw_thread_stl/public_overrides/pw_thread_backend/yield_inline.h

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Copyright 2020 The Pigweed Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
// use this file except in compliance with the License. You may obtain a copy of
5+
// the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
// License for the specific language governing permissions and limitations under
13+
// the License.
14+
#pragma once
15+
16+
#include "pw_thread_stl/yield_inline.h"

‎targets/host/target_toolchains.gni

+7
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import("$dir_pw_rpc/system_server/backend.gni")
2020
import("$dir_pw_sync/backend.gni")
2121
import("$dir_pw_sys_io/backend.gni")
2222
import("$dir_pw_third_party/nanopb/nanopb.gni")
23+
import("$dir_pw_thread/backend.gni")
2324
import("$dir_pw_toolchain/host_clang/toolchains.gni")
2425
import("$dir_pw_toolchain/host_gcc/toolchains.gni")
2526

@@ -79,10 +80,16 @@ _win_config = {
7980
# TODO(amontanez): figure out why std::mutex doesn't work on Windows.
8081
# These current target configurations do not work on windows.
8182
_win_incompatible_config = {
83+
# Configure backends for pw_sync's facades.
8284
pw_sync_BINARY_SEMAPHORE_BACKEND = "$dir_pw_sync_stl:binary_semaphore_backend"
8385
pw_sync_COUNTING_SEMAPHORE_BACKEND =
8486
"$dir_pw_sync_stl:counting_semaphore_backend"
8587
pw_sync_MUTEX_BACKEND = "$dir_pw_sync_stl:mutex_backend"
88+
89+
# Configure backends for pw_thread's facades.
90+
pw_thread_ID_BACKEND = "$dir_pw_thread_stl:id"
91+
pw_thread_SLEEP_BACKEND = "$dir_pw_thread_stl:sleep"
92+
pw_thread_YIELD_BACKEND = "$dir_pw_thread_stl:yield"
8693
}
8794

8895
_os_specific_config = {

0 commit comments

Comments
 (0)
Please sign in to comment.