If a value has not been previously set (i.e. pthread_getspecific returned 0), pthread_setspecific may allocate. Therefore, calling it in a signal handler is unsafe.

I suggest pthread_setspecific is called just once per thread at a safe point. It will be used to install a pointer to the variable to be incremented. Besides signal safety, I see additional benefits of this approach:

• A counter will be incremented only for those threads that have "subscribed" to the event by installing a thread-local pointer.
• If an application caches the pointer, it can query the counter efficiently without making an API call. This is especially useful for Java, since it will be possible to read the counter directly in Java without JNI overhead.
• In the future, this can be easily extended to pass additional context information between async-profiler and an appication via the same thread-local.

The question remains, who will call pthread_setspecific and when.

turned out you can do it in asprof_get_sample_counter since the API lets you

We discussed this would be an experimental (unstable) API? No need to document it then... or there should be an explicit notice.

Implementation of asprof_ APIs should be in asprof.cpp.

I'm thinking where the right place to increment the counter will be.
The counter is only relevant with JFR output, isn't it? Then recordEvent (or the places where it is called) seems a better alternative. Or can you imagine a different use case?
Note that some recorded events (e.g. free calls in native memory profiling mode) bypass Profiler::recordSample.

Just an idea: what do you think about asprof_get_tls function instead? It will return a pointer to the entire thread local area, which besides the counter may include other context-related information.
I'll certainly need something like this for Java API.

Implementation-wise, your previous revision was cleaner, IMO. Why have you switched to a lazy initialization of pthread_key? This seems to add unnecessary complication to ensure thread safety etc.

1. I couldn't find a good non-lazy place to initialize it
2. people might call asprof_get_thread_local_data concurrently with initializing async-profiler, I want that to work.

Async-profiler has its own Mutex and MutexLocker classes. I'm generally cautious in adopting more libstdc++ features: libstdc++ caused many issues in the past, so I even wanted to get rid of it entirely, see #872.

You've explicitly documented the function as unstable in the code and in the docs, which is totally fine; adding unstable in the name is going to be too much ) The name is already too long.

This "private" header looks somewhat artificial design-wise. There is no real division into public/private headers in the sources.
It's true that asprof.h lists publicly exported functions, and it's OK for other parts of the profiler to use these functions, but if some source needs to call an internal function, then this function has likely nothing to do with asprof* API.
In your particular case, FlightRecorder is the only caller of asprofIncrementThreadLocalSampleCounter, so why can't this function be a part of FlightRecorder then? Or perhaps a member of Profiler? When we have more thread local data in the future, it may be reasonable to extract these functions to a separate threadLocal.{h,cpp} or tls.{h,cpp}.

With rare exceptions, non-local top-level functions are discouraged in async-profiler.
Static classes generally serve as namespaces. Actual C++ namespaces would be probably better, but that was a historical choice similar to the coding style adopted in HotSpot.

unstable in the name remained