C++20 modules and `std::jthread`: link failed with clang & libc++ v21.1.x

[bshoshany]

I ran into this issue when compiling my thread pool library using Clang in C++20 module mode. After some investigation I was able to pin the issue down to using std::jthread in both the module and the program that imports it. I created the following minimal working example:

// jthread_error.cppm
module;
#include <thread>
export module jthread_error;
export struct jthread_error_struct { std::jthread thread; };

// jthread_error.cpp
#include <thread>
import jthread_error;
int main() { jthread_error_struct test; }

Compile with:

clang++ jthread_error.cppm --precompile -std=c++20 -I include -o jthread_error.pcm -stdlib=libc++
clang++ jthread_error.cpp -fmodule-file="jthread_error=jthread_error.pcm" -std=c++20 -o jthread_error -stdlib=libc++

When I try this on Windows 11 25H2 build 26200.7462 with Clang and libc++ v21.1.7 installed via MSYS2 in the CLANG64 environment, I get the following error:

ld.lld: error: undefined symbol: std::__1::__atomic_unique_lock<unsigned int, 2u>::__set_locked_bit[abi:ne210107]
>>> referenced by C:/Users/barak/AppData/Local/Temp/jthread_error-c6c4a2.o:(.refptr._ZNSt3__120__atomic_unique_lockIjLj2EE16__set_locked_bitB8ne210107E)
clang++: error: linker command failed with exit code 1 (use -v to see invocation)

Similarly, when I try this on Ubuntu 25.10 with Clang and libc++ v21.1.8 installed via apt, I get the following error:

/usr/bin/ld: /tmp/jthread_error-a7e681.o: in function `std::__1::__atomic_unique_lock<unsigned int, 2u>::__lock[abi:ne210108]()':
jthread_error.cpp:(.text._ZNSt3__120__atomic_unique_lockIjLj2EE6__lockB8ne210108Ev[_ZNSt3__120__atomic_unique_lockIjLj2EE6__lockB8ne210108Ev]+0x24): undefined reference to `std::__1::__atomic_unique_lock<unsigned int, 2u>::__set_locked_bit[abi:ne210108]'  
/usr/bin/ld: jthread_error: hidden symbol `_ZNSt3__120__atomic_unique_lockIjLj2EE16__set_locked_bitB8ne210108E' isn't defined   
/usr/bin/ld: final link failed: bad value
clang++: error: linker command failed with exit code 1 (use -v to see invocation)

Note that this does not happen on any other compiler I tested, nor does it happen with Clang when using -stdlib=libstdc++ on Ubuntu or the native Windows LLVM release (using the MSVC standard library), or with libc++ if using std::thread instead of std::jthread.

Could this be an issue with libc++ itself?

[llvmbot]

@llvm/issue-subscribers-clang-modules

Author: Barak Shoshany (bshoshany)

Details

I ran into this issue when compiling [my thread pool library](https://github.com/bshoshany/thread-pool) using Clang in C++20 module mode. After some investigation I was able to pin the issue down to using `std::jthread` in both the module and the program that imports it. I created the following minimal working example:

// jthread_error.cppm
module;
#include <thread>
export module jthread_error;
export struct jthread_error_struct { std::jthread thread; };

// jthread_error.cpp
#include <thread>
import jthread_error;
int main() { jthread_error_struct test; }

Compile with:

clang++ jthread_error.cppm --precompile -std=c++20 -I include -o jthread_error.pcm -stdlib=libc++
clang++ jthread_error.cpp -fmodule-file="jthread_error=jthread_error.pcm" -std=c++20 -o jthread_error -stdlib=libc++

When I try this on Windows 11 25H2 build 26200.7462 with Clang and libc++ v21.1.7 installed via MSYS2 in the CLANG64 environment, I get the following error:

ld.lld: error: undefined symbol: std::__1::__atomic_unique_lock<unsigned int, 2u>::__set_locked_bit[abi:ne210107]
>>> referenced by C:/Users/barak/AppData/Local/Temp/jthread_error-c6c4a2.o:(.refptr._ZNSt3__120__atomic_unique_lockIjLj2EE16__set_locked_bitB8ne210107E)
clang++: error: linker command failed with exit code 1 (use -v to see invocation)

Similarly, when I try this on Ubuntu 25.10 with Clang and libc++ v21.1.8 installed via apt, I get the following error:

/usr/bin/ld: /tmp/jthread_error-a7e681.o: in function `std::__1::__atomic_unique_lock<unsigned int, 2u>::__lock[abi:ne210108]()':
jthread_error.cpp:(.text._ZNSt3__120__atomic_unique_lockIjLj2EE6__lockB8ne210108Ev[_ZNSt3__120__atomic_unique_lockIjLj2EE6__lockB8ne210108Ev]+0x24): undefined reference to `std::__1::__atomic_unique_lock<unsigned int, 2u>::__set_locked_bit[abi:ne210108]'  
/usr/bin/ld: jthread_error: hidden symbol `_ZNSt3__120__atomic_unique_lockIjLj2EE16__set_locked_bitB8ne210108E' isn't defined   
/usr/bin/ld: final link failed: bad value
clang++: error: linker command failed with exit code 1 (use -v to see invocation)

Note that this does not happen on any other compiler I tested, nor does it happen with Clang when using -stdlib=libstdc++ on Ubuntu or the native Windows LLVM release (using the MSVC standard library), or with libc++ if using std::thread instead of std::jthread.

Could this be an issue with libc++ itself?

[ChuanqiXu9]

From your commands, it looks you didn't link the object file generated from .pcm files. That is required.

BTW, given you're using high level libcxx version, import std is recommended.

[bshoshany]

Thanks for your quick reply, @ChuanqiXu9! I don't see any object file; it only generates the .pcm file. What would be the correct commands to generate and include the object file?

When I use import std this indeed doesn't happen, but some people don't use C++23 or don't use import std for various reasons, and I want to make sure my library works for everyone.

[ChuanqiXu9]

Thanks for your quick reply, @ChuanqiXu9! I don't see any object file; it only generates the .pcm file. What would be the correct commands to generate and include the object file?

When I use import std this indeed doesn't happen, but some people don't use C++23 or don't use import std for various reasons, and I want to make sure my library works for everyone.

Please look at https://clang.llvm.org/docs/StandardCPlusPlusModules.html#remember-that-module-units-still-have-an-object-counterpart-to-the-bmi and https://clang.llvm.org/docs/StandardCPlusPlusModules.html#quick-start

In the quick start example, it compiles Hello.pcm file to Hello.o implicitly

[ChuanqiXu9]

When I use import std this indeed doesn't happen, but some people don't use C++23

BTW, import std; should be C++20 feature in practice, this is decided by vendors. microsoft/STL#3945

[bshoshany]

Thanks again! I tried compiling the module to an object file first, but this did not solve the problem.

In the first Quick Start example, they do not create an object file, but it still works, because - as you said - an object file is created implicitly anyway. In the second example, they do create an object file, but this doesn't seem to be a necessary step.

I will also note that in my thread pool library the compilation does work if I change std::jthread to std::thread; I do not need to compile to an object file explicitly for this to work. The problem only appears when using std::jthread specifically, and only with libc++.

So it seems to me like a bug in libc++ itself. I may be mistaken; if you could try compiling my example and let me know the correct command line to make it compile successfully, I would really appreciate it!

Otherwise, if this is really a bug in libc++, I wonder why it is happening and how it can be fixed, and in particular, if there's something I can do on my end to fix/avoid it (e.g. add specific command line arguments) or if this is something that has to be fixed in the library itself?

[bshoshany]

After investigating a bit more, I realized that a simple workaround is to move #include <thread> after import jthread_error. However, I cannot guarantee that all the users of my library will always order their includes and imports in exactly this way (just as I cannot guarantee that they will use import std), and I still believe this is an issue in libc++ itself (because it doesn't reproduce with any other compiler or standard library or with any class other than std::jthread or header file other than <thread>), and therefore it should be fixed. I would greatly appreciate any input on this!

[ChuanqiXu9]

Reproduced.

Could this be an issue with libc++ itself?

I don't have a conclusion yet. But I feel this may be a clang bug more.

[ChuanqiXu9]

After investigating a bit more, I realized that a simple workaround is to move #include after import jthread_error.

For the bug itself, if you want to workaround, it seems we can remove the #include directly

[bshoshany]

For the bug itself, if you want to workaround, it seems we can remove the #include directly

In the toy example above, yes, but in the general case someone might want to use something from <thread> in their own program and also import a module that uses std::jthread (for example, that's what my test program does).

Reproduced.

Great! Glad to know it's not just me.

I don't have a conclusion yet. But I feel this may be a clang bug more.

Looking forward to your assessment! Thanks again!

[ChuanqiXu9]

Confirmed to be a clang bug.

---

(For devs)

Minimal Reproducer:

// RUN: rm -rf %t
// RUN: mkdir -p %t
// RUN: split-file %s %t
//
// RUNX: %clang_cc1 -std=c++20 -triple %itanium_abi_triple %t/use_header.cpp -emit-llvm -o - | FileCheck %t/use_header.cpp
// RUN: %clang_cc1 -std=c++20 -triple %itanium_abi_triple %t/m.cppm -emit-module-interface -o %t/m.pcm
// RUN: %clang_cc1 -std=c++20 -triple %itanium_abi_triple %t/use.cpp -fmodule-file=m=%t/m.pcm -emit-llvm -o - | FileCheck %t/use.cpp

//--- header.h
#pragma once

template <unsigned T>
class Templ {
public:
    void lock() { __set_locked_bit(); }

private:
    static constexpr auto __set_locked_bit = [](){};
};

class JT {
public:
    ~JT() {
        Templ<4> state;
        state.lock();
    }
};

//--- use_header.cpp
#include "header.h"

int main() {
    JT jt;
    return 0;
}

// CHECK: @_ZN5TemplILj4EE16__set_locked_bitE = {{.*}}linkonce_odr

//--- m.cppm
module;
#include "header.h"
export module m;
export struct M {
    JT jt;
};
//--- use.cpp
#include "header.h"
import m;

int main() {
    M m;
    return 0;
}

// CHECK: @_ZN5TemplILj4EE16__set_locked_bitE = {{.*}}linkonce_odr

If we remove import, and move the definition for M to use.cpp, then we can emit the definition when instantiate the variable decl for Templ::__set_locked_bit.

If we remove the #include, we can emit the definition when we read the definition from module file.

The funny part is, when we have both import and #include, we may have an "optimization", which marks the definition inside the module file as declaration:

llvm-project/clang/lib/Serialization/ASTReaderDecl.cpp

Lines 3649 to 3660 in 1eba2cb

	// We should keep at most one definition on the chain.
	// FIXME: Cache the definition once we've found it. Building a chain with
	// N definitions currently takes O(N^2) time here.
	if (VD->isThisDeclarationADefinition() == VarDecl::Definition) {
	for (VarDecl *CurD = PrevVD; CurD; CurD = CurD->getPreviousDecl()) {
	if (CurD->isThisDeclarationADefinition() == VarDecl::Definition) {
	Reader.mergeDefinitionVisibility(CurD, VD);
	VD->demoteThisDefinitionToDeclaration();
	break;
	}
	}
	}