[Support] Add functions to get and set thread name.

[zturner]

Summary

It is often useful however for an application to set the names of its various threads for diagnostic purposes, either when logging or when debugging the application with a debugger that understands how to display thread names.

Because it is extremely non-portable, the methods for getting and setting thread names vary wildly on each platform, and not all operations are supported on every platform.

Regardless, since it is non-critical functionality used mostly for diagnostics, it seems reasonable to provide "best effort" functions, which is what this patch does. This code is a modified version of the logic in LLDB for doing the same thing. If people don't want this, I can always leave it in LLDB, but since it's so hard to make portable and since LLDB has implementations for a lot of different platforms, it might be useful to have it available to anyone who wants it.

Here I provide implementations for the following platforms / operations:

GetName - FreeBSD, NetBSD, Linux.
SetName - Linux, FreeBSD, NetBSD, Apple, Windows.

It's probably possible to do this on many other platforms, but this is already a lot for one person :)

The implementations have already been in use for some time on LLDB so I know they work, but in re-writing the code for LLDB I may have made some syntax errors.

[zturner]

Fix a mistake in the linux implementation. I originally had this returning an llvm::Error, but it seemed obnoxious / unnecessary to have to check the return value of a function which is documented as being "best effort"

[davide]

The FreeBSD related bits are correct. The whole chain of #ifdef is a little nasty, but I'm not sure there's an easy way to avoid it.

llvm/lib/Support/Threading.cpp

158–170 ↗

(On Diff #90288)

I'm wondering if there's a way to avoid this ugly #ifdef dance.

[davide]

llvm/lib/Support/Threading.cpp

43–50 ↗

(On Diff #90288)

The inner `#if defined(FreeBSD) is redundant, maybe? (as you're doing the same outside)

158–163 ↗

(On Diff #90288)

Maybe you can merge these two cases?

164–166 ↗

(On Diff #90288)

Amazing how 4 operating systems define pretty much the same call with slightly different variants.

[labath]

llvm/lib/Support/Threading.cpp

155 ↗

(On Diff #90288)

It might be overkill, but you could potentially save a copy if you use the Twine.toNullTerminatedStringRef trick

248 ↗

(On Diff #90288)

This is not correct. pthread_self returns a pthread_t, which bears no relation to the OS-level thread ID's. You'd need to use syscall(SYS_gettid) here. Also according to the docs http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html it seems a better file to read would be /proc/self/task/<tid>/comm. As was as I know these files always have the same contents, but maybe the other one is deprecated (?)

However, the main issue here is that the set and get code are wildly out of sync. There is a pthread_getname_np pair to the pthread_setname_np (see manpage above), so we should either use that here (guarded by the same ifdefs), or switch the setting code to write directly to the file as well (these functions are basically documented as utilities for reading/writing the file).

I'm sorry I am dumping this on you, but I think the llvm bar for this should be higher than in lldb. I can do this next week if you don't feel comfortable touching that.

[zturner]

Updated with suggestions from labath@

[zturner]

llvm/lib/Support/Threading.cpp

43–50 ↗

(On Diff #90288)

I don't think pthread_np.h exists on the other flavors of BSD though right? (I actually dont' know, but this is how I translated the code from LLDB. NetBSD and FreeBSD Kernel were not including these headers.

158–163 ↗

(On Diff #90288)

The name of the function is slightly different though. For FreeBSD there is an extra underscore. So I have to paper over that difference with a #define somewhere, even if not here.

164–166 ↗

(On Diff #90288)

I know right? Very annoying :-/

[zturner]

Also added a function to get the current thread id. std::this_thread::get_id(), unfortunately cannot be examined portably.

[zturner]

This file is starting to get pretty unwieldy, so I suppose it's time to split it into the .inc files. This makes the preprocessor stuff slightly less terrible.

[zturner]

Fixed a compiler error. This now compiles on Linux, Windows, and OSX. Don't have the ability to test any other configurations but I think I got all the includes right.

[labath]

Thank you, it looks much better. Let me know what you think about the name.

llvm/include/llvm/Support/Threading.h

133 ↗

(On Diff #90421)

I'd remove the _np suffix. It is present on the pthread functions to differentiate them from other pthread_*** functions, which are expected to behave the same on all conforming implementations. Since the purpose of this function is to provide a *portable* wrapper around different versions of those functions, having the suffix here seems wrong.

llvm/lib/Support/Unix/Threading.inc

100 ↗

(On Diff #90421)

I am wondering whether this is a useful fallback. pthread_t is used in completely different contexts than OS-level thread handles, so it may be better to just return 0 or something here. I don't feel strongly about it though.

[labath]

I think the same goes for net/freebsd threads as well. Potentially we could document that the thread id only makes sense within the context of the current process, but I think that's about it.

looks good as far as I am concerned.

[krytarowski]

I will improve this code for NetBSD as we must not include <sys/user.h>. This header is long empty and it will be removed.

[thakis]

llvm/trunk/lib/Support/Unix/Threading.inc

98

LLVM_ON_WIN32 will never be set in Unix/Threading.inc, will it? Is this branch ever used?

[zturner]

Hmm I don’t remember why i did that, certainly looks like an accident

[thakis]

Removed it in r331151, thanks!

[TomTan]

Hi Zachary, does this line "#include "Windows/WindowsSupport.h" " need to be changed to "#include "WindowsSupport.h" " after it is moved from Threading.cpp to Threading.inc, because Threading.inc which includes WindowsSupport.h is under Windows folder, so no need to have it in the include path. This current include path could trigger warning "#include resolved using non-portable Microsoft search rules as: ..."

llvm/trunk/include/llvm/Support/Threading.h

 // This file declares helper functions for running LLVM in a multi-threaded
 // environment.
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_SUPPORT_THREADING_H
 #define LLVM_SUPPORT_THREADING_H
 
+#include "llvm/ADT/SmallVector.h"
 #include "llvm/Config/llvm-config.h" // for LLVM_ON_UNIX
 #include "llvm/Support/Compiler.h"
 #include <ciso646> // So we can check the C++ standard lib macros.
 #include <functional>
 
 #if defined(_MSC_VER)
 // MSVC's call_once implementation worked since VS 2015, which is the minimum
 // supported version as of this writing.

 
 #if LLVM_THREADING_USE_STD_CALL_ONCE
 #include <mutex>
 #else
 #include "llvm/Support/Atomic.h"
 #endif
 
 namespace llvm {
-  /// Returns true if LLVM is compiled with support for multi-threading, and
-  /// false otherwise.
-  bool llvm_is_multithreaded();
+class Twine;
+
 
-  /// llvm_execute_on_thread - Execute the given \p UserFn on a separate
-  /// thread, passing it the provided \p UserData and waits for thread
-  /// completion.
-  ///
-  /// This function does not guarantee that the code will actually be executed
-  /// on a separate thread or honoring the requested stack size, but tries to do
-  /// so where system support is available.
-  ///
-  /// \param UserFn - The callback to execute.
-  /// \param UserData - An argument to pass to the callback function.
-  /// \param RequestedStackSize - If non-zero, a requested size (in bytes) for
-  /// the thread stack.
-  void llvm_execute_on_thread(void (*UserFn)(void*), void *UserData,
-                              unsigned RequestedStackSize = 0);
+void llvm_execute_on_thread(void (*UserFn)(void *), void *UserData,
 
 #if LLVM_THREADING_USE_STD_CALL_ONCE
 
   typedef std::once_flag once_flag;
 
 #else
 
   enum InitStatus { Uninitialized = 0, Wait = 1, Done = 2 };
#endif
   }
 
   /// Get the amount of currency to use for tasks requiring significant
   /// memory or other resources. Currently based on physical cores, if
   /// available for the host system, otherwise falls back to
   /// thread::hardware_concurrency().
   /// Returns 1 when LLVM is configured with LLVM_ENABLE_THREADS=OFF
   unsigned heavyweight_hardware_concurrency();
+
+  /// \brief Return the current thread id, as used in various OS system calls.
+  /// Note that not all platforms guarantee that the value returned will be
+  /// unique across the entire system, so portable code should not assume
+  /// this.
+  uint64_t get_threadid();
+
+  /// \brief Set the name of the current thread.  Setting a thread's name can
+  /// be helpful for enabling useful diagnostics under a debugger or when
+  /// logging.  The level of support for setting a thread's name varies
+  /// wildly across operating systems, and we only make a best effort to
+  /// perform the operation on supported platforms.  No indication of success
+  /// or failure is returned.
+  void set_thread_name(const Twine &Name);
+
+  /// \brief Get the name of the current thread.  The level of support for
+  /// getting a thread's name varies wildly across operating systems, and it
+  /// is not even guaranteed that if you can successfully set a thread's name
+  /// that you can later get it back.  This function is intended for diagnostic
+  /// purposes, and as with setting a thread's name no indication of whether
+  /// the operation succeeded or failed is returned.
+  void get_thread_name(SmallVectorImpl<char> &Name);
 }
 
 #endif

llvm/trunk/lib/Support/Threading.cpp

 //===-- llvm/Support/Threading.cpp- Control multithreading mode --*- C++ -*-==//
 //
 //                     The LLVM Compiler Infrastructure
 //
 // This file is distributed under the University of Illinois Open Source
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
 //
 // This file defines helper functions for running LLVM in a multi-threaded
 // environment.
 //
 //===----------------------------------------------------------------------===//
 
 #include "llvm/Support/Threading.h"
 #include "llvm/Config/config.h"
-#include "llvm/Support/Atomic.h"
 #include "llvm/Support/Host.h"
-#include "llvm/Support/Mutex.h"
 #include "llvm/Support/thread.h"
+
 #include <cassert>
+#include <errno.h>
+#include <stdlib.h>
+#include <string.h>
 
 using namespace llvm;
 
+//===----------------------------------------------------------------------===//
+//=== WARNING: Implementation here must contain only TRULY operating system
+//===          independent code.
+//===----------------------------------------------------------------------===//
+
 bool llvm::llvm_is_multithreaded() {
 #if LLVM_ENABLE_THREADS != 0
   return true;
 #else
   return false;
 #endif
 }
 
-#if LLVM_ENABLE_THREADS != 0 && defined(HAVE_PTHREAD_H)
-#include <pthread.h>
-
-struct ThreadInfo {
-  void (*UserFn)(void *);
-  void *UserData;
-};
-static void *ExecuteOnThread_Dispatch(void *Arg) {
-  ThreadInfo *TI = reinterpret_cast<ThreadInfo*>(Arg);
-  TI->UserFn(TI->UserData);
-  return nullptr;
-}
-
-void llvm::llvm_execute_on_thread(void (*Fn)(void*), void *UserData,
+#if LLVM_ENABLE_THREADS == 0 ||                                                \
+    (!defined(LLVM_ON_WIN32) && !defined(HAVE_PTHREAD_H))
+// Support for non-Win32, non-pthread implementation.
+void llvm::llvm_execute_on_thread(void (*Fn)(void *), void *UserData,
                                   unsigned RequestedStackSize) {
-  ThreadInfo Info = { Fn, UserData };
-  pthread_attr_t Attr;
-  pthread_t Thread;
-
-  // Construct the attributes object.
-  if (::pthread_attr_init(&Attr) != 0)
-    return;
-
-  // Set the requested stack size, if given.
-  if (RequestedStackSize != 0) {
-    if (::pthread_attr_setstacksize(&Attr, RequestedStackSize) != 0)
-      goto error;
-  }
+  (void)RequestedStackSize;
+  Fn(UserData);
 
-  // Construct and execute the thread.
-  if (::pthread_create(&Thread, &Attr, ExecuteOnThread_Dispatch, &Info) != 0)
-    goto error;
-
-  // Wait for the thread and clean up.
-  ::pthread_join(Thread, nullptr);
-
- error:
-  ::pthread_attr_destroy(&Attr);
-}
-#elif LLVM_ENABLE_THREADS!=0 && defined(LLVM_ON_WIN32)
-#include "Windows/WindowsSupport.h"
-#include <process.h>
-
-// Windows will at times define MemoryFence.
-#ifdef MemoryFence
-#undef MemoryFence
-#endif
+unsigned llvm::heavyweight_hardware_concurrency() { return 1; }
 
-struct ThreadInfo {
-  void (*func)(void*);
-  void *param;
-};
-
-static unsigned __stdcall ThreadCallback(void *param) {
-  struct ThreadInfo *info = reinterpret_cast<struct ThreadInfo *>(param);
-  info->func(info->param);
+uint64_t llvm::get_threadid_np() { return 0; }
 
-  return 0;
-}
+void llvm::set_thread_name(const Twine &Name) {}
 
-void llvm::llvm_execute_on_thread(void (*Fn)(void*), void *UserData,
-                                  unsigned RequestedStackSize) {
-  struct ThreadInfo param = { Fn, UserData };
+void llvm::get_thread_name(SmallVectorImpl<char> &Name) { Name.clear(); }
 
-  HANDLE hThread = (HANDLE)::_beginthreadex(NULL,
-                                            RequestedStackSize, ThreadCallback,
-                                            &param, 0, NULL);
-
-  if (hThread) {
-    // We actually don't care whether the wait succeeds or fails, in
-    // the same way we don't care whether the pthread_join call succeeds
-    // or fails.  There's not much we could do if this were to fail. But
-    // on success, this call will wait until the thread finishes executing
-    // before returning.
-    (void)::WaitForSingleObject(hThread, INFINITE);
-    ::CloseHandle(hThread);
-  }
-}
 #else
-// Support for non-Win32, non-pthread implementation.
-void llvm::llvm_execute_on_thread(void (*Fn)(void*), void *UserData,
-                                  unsigned RequestedStackSize) {
-  (void) RequestedStackSize;
-  Fn(UserData);
-}
-
-#endif
 
 unsigned llvm::heavyweight_hardware_concurrency() {
-#if !LLVM_ENABLE_THREADS
-  return 1;
-#endif
   int NumPhysical = sys::getHostNumPhysicalCores();
   if (NumPhysical == -1)
     return thread::hardware_concurrency();
   return NumPhysical;
 }
+
+// Include the platform-specific parts of this class.
+#ifdef LLVM_ON_UNIX
+#include "Unix/Threading.inc"
+#endif
+#ifdef LLVM_ON_WIN32
+#include "Windows/Threading.inc"
+#endif
+
+#endif

llvm/trunk/lib/Support/Unix/Threading.inc

+//===- Unix/Threading.inc - Unix Threading Implementation ----- -*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+//
+// This file provides the Unix specific implementation of Threading functions.
+//
+//===----------------------------------------------------------------------===//
+
+#include "llvm/ADT/SmallString.h"
+#include "llvm/ADT/Twine.h"
+
+#if defined(__APPLE__)
+#include <mach/mach_init.h>
+#include <mach/mach_port.h>
+#endif
+
+#include <pthread.h>
+
+#if defined(__FreeBSD__)
+#include <pthread_np.h>
+#endif
+
+#if defined(__NetBSD__)
+#include <lwp.h>
+#endif
+
+#if defined(__linux__)
+#include <sys/syscall.h>
+#endif
+
+#if defined(__NetBSD__) || defined(__FreeBSD__) || defined(__FreeBSD_kernel__)
+#include <sys/sysctl.h>
+#include <sys/user.h>
+#endif
+
+namespace {
+  struct ThreadInfo {
+    void(*UserFn)(void *);
+    void *UserData;
+  };
+}
+
+static void *ExecuteOnThread_Dispatch(void *Arg) {
+  ThreadInfo *TI = reinterpret_cast<ThreadInfo*>(Arg);
+  TI->UserFn(TI->UserData);
+  return nullptr;
+}
+
+void llvm::llvm_execute_on_thread(void(*Fn)(void*), void *UserData,
+  unsigned RequestedStackSize) {
+  ThreadInfo Info = { Fn, UserData };
+  pthread_attr_t Attr;
+  pthread_t Thread;
+
+  // Construct the attributes object.
+  if (::pthread_attr_init(&Attr) != 0)
+    return;
+
+  // Set the requested stack size, if given.
+  if (RequestedStackSize != 0) {
+    if (::pthread_attr_setstacksize(&Attr, RequestedStackSize) != 0)
+      goto error;
+  }
+
+  // Construct and execute the thread.
+  if (::pthread_create(&Thread, &Attr, ExecuteOnThread_Dispatch, &Info) != 0)
+    goto error;
+
+  // Wait for the thread and clean up.
+  ::pthread_join(Thread, nullptr);
+
+error:
+  ::pthread_attr_destroy(&Attr);
+}
+
+
+uint64_t llvm::get_threadid() {
+#if defined(__APPLE__)
+  // Calling "mach_thread_self()" bumps the reference count on the thread
+  // port, so we need to deallocate it. mach_task_self() doesn't bump the ref
+  // count.
+  thread_port_t Self = mach_thread_self();
+  mach_port_deallocate(mach_task_self(), Self);
+  return Self;
+#elif defined(__FreeBSD__)
+  return uint64_t(pthread_getthreadid_np());
+#elif defined(__NetBSD__)
+  return uint64_t(_lwp_self());
+#elif defined(__ANDROID__)
+  return uint64_t(gettid());
+#elif defined(__linux__)
+  return uint64_t(syscall(SYS_gettid));
+#elif defined(LLVM_ON_WIN32)
+  return uint64_t(::GetCurrentThreadId());
+#else
+  return uint64_t(pthread_self());
+#endif
+}
+
+
+void llvm::set_thread_name(const Twine &Name) {
+  // Make sure the input is null terminated.
+  SmallString<64> Storage;
+  StringRef NameStr = Name.toNullTerminatedStringRef(Storage);
+#if defined(__linux__)
+#if (defined(__GLIBC__) && defined(_GNU_SOURCE)) || defined(__ANDROID__)
+  ::pthread_setname_np(::pthread_self(), NameStr.data());
+#endif
+#elif defined(__FreeBSD__)
+  ::pthread_set_name_np(::pthread_self(), NameStr.data());
+#elif defined(__NetBSD__)
+  ::pthread_setname_np(::pthread_self(), "%s",
+    const_cast<char *>(NameStr.data()));
+#elif defined(__APPLE__)
+  ::pthread_setname_np(NameStr.data());
+#endif
+}
+
+void llvm::get_thread_name(SmallVectorImpl<char> &Name) {
+  Name.clear();
+
+#if defined(__FreeBSD__) || defined(__FreeBSD_kernel__)
+#if defined(__FreeBSD_kernel__)
+  int pid = ::pthread_self();
+#else
+  int pid = ::getpid();
+#endif
+
+  int tid = ::pthread_getthreadid_np();
+
+  struct kinfo_proc *kp = nullptr, *nkp;
+  size_t len = 0;
+  int error;
+  int ctl[4] = { CTL_KERN, KERN_PROC, KERN_PROC_PID | KERN_PROC_INC_THREAD,
+    (int)pid };
+
+  while (1) {
+    error = sysctl(ctl, 4, kp, &len, nullptr, 0);
+    if (kp == nullptr || (error != 0 && errno == ENOMEM)) {
+      // Add extra space in case threads are added before next call.
+      len += sizeof(*kp) + len / 10;
+      nkp = (struct kinfo_proc *)realloc(kp, len);
+      if (nkp == nullptr) {
+        free(kp);
+        return;
+      }
+      kp = nkp;
+      continue;
+    }
+    if (error != 0)
+      len = 0;
+    break;
+  }
+
+  for (size_t i = 0; i < len / sizeof(*kp); i++) {
+    if (kp[i].ki_tid == (lwpid_t)tid) {
+      Name.append(kp[i].ki_tdname, kp[i].ki_tdname + strlen(kp[i].ki_tdname));
+      break;
+    }
+  }
+  free(kp);
+  return;
+#elif defined(__NetBSD__)
+  char buf[PTHREAD_MAX_NAMELEN_NP];
+  ::pthread_getname_np(::pthread_self(), buf, PTHREAD_MAX_NAMELEN_NP);
+
+  Name.append(buf, buf + strlen(buf));
+#elif defined(__linux__)
+#if (defined(__GLIBC__) && defined(_GNU_SOURCE)) || defined(__ANDROID__)
+  constexpr int MAXNAMELEN = 16;
+  char Buffer[MAXNAMELEN];
+  if (0 == ::pthread_getname_np(::pthread_self(), Buffer, MAXNAMELEN))
+    Name.append(Buffer, Buffer + strlen(Buffer));
+#endif
+#endif
+}

llvm/trunk/lib/Support/Windows/Threading.inc

+//===- Windows/Threading.inc - Win32 Threading Implementation - -*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+//
+// This file provides the Win32 specific implementation of Threading functions.
+//
+//===----------------------------------------------------------------------===//
+
+#include "llvm/ADT/SmallString.h"
+#include "llvm/ADT/Twine.h"
+
+#include "Windows/WindowsSupport.h"
+#include <process.h>
+
+// Windows will at times define MemoryFence.
+#ifdef MemoryFence
+#undef MemoryFence
+#endif
+
+namespace {
+  struct ThreadInfo {
+    void(*func)(void*);
+    void *param;
+  };
+}
+
+static unsigned __stdcall ThreadCallback(void *param) {
+  struct ThreadInfo *info = reinterpret_cast<struct ThreadInfo *>(param);
+  info->func(info->param);
+
+  return 0;
+}
+
+void llvm::llvm_execute_on_thread(void(*Fn)(void*), void *UserData,
+  unsigned RequestedStackSize) {
+  struct ThreadInfo param = { Fn, UserData };
+
+  HANDLE hThread = (HANDLE)::_beginthreadex(NULL,
+    RequestedStackSize, ThreadCallback,
+    &param, 0, NULL);
+
+  if (hThread) {
+    // We actually don't care whether the wait succeeds or fails, in
+    // the same way we don't care whether the pthread_join call succeeds
+    // or fails.  There's not much we could do if this were to fail. But
+    // on success, this call will wait until the thread finishes executing
+    // before returning.
+    (void)::WaitForSingleObject(hThread, INFINITE);
+    ::CloseHandle(hThread);
+  }
+}
+
+uint64_t llvm::get_threadid() {
+  return uint64_t(::GetCurrentThreadId());
+}
+
+void llvm::set_thread_name(const Twine &Name) {
+#if defined(_MSC_VER)
+  // Make sure the input is null terminated.
+  SmallString<64> Storage;
+  StringRef NameStr = Name.toNullTerminatedStringRef(Storage);
+  constexpr DWORD MS_VC_EXCEPTION = 0x406D1388;
+
+#pragma pack(push, 8)
+  struct THREADNAME_INFO {
+    DWORD dwType;     // Must be 0x1000.
+    LPCSTR szName;    // Pointer to thread name
+    DWORD dwThreadId; // Thread ID (-1 == current thread)
+    DWORD dwFlags;    // Reserved.  Do not use.
+  };
+#pragma pack(pop)
+
+  THREADNAME_INFO info;
+  info.dwType = 0x1000;
+  info.szName = NameStr.data();
+  info.dwThreadId = ::GetCurrentThreadId();
+  info.dwFlags = 0;
+
+  __try {
+    ::RaiseException(MS_VC_EXCEPTION, 0, sizeof(info) / sizeof(ULONG_PTR),
+      (ULONG_PTR *)&info);
+  }
+  __except (EXCEPTION_EXECUTE_HANDLER) {
+  }
+#endif
+}
+
+void llvm::get_thread_name(SmallVectorImpl<char> &Name) {
+  // "Name" is not an inherent property of a thread on Windows.  In fact, when
+  // you "set" the name, you are only firing a one-time message to a debugger
+  // which it interprets as a program setting its threads' name.  We may be
+  // able to get fancy by creating a TLS entry when someone calls
+  // set_thread_name so that subsequent calls to get_thread_name return this
+  // value.
+  Name.clear();
+}