title: Returning thread-local data from a shared library C-api
body: <p><strong>Question 1:</strong> Is it safe and portable to return a pointer to a thread_local data from a shared library providing a traditional C-API? </p>
  
  <p>The lib itself is naturally implemented with C++11. Safetyness in respect to memory leaks and race conditions, portablitity covering the main desktop OSs: Windows, Linux and OSX. The calling application might be for example native, Java, C#, etc.</p>
  
  <p>The use case is to implement caller-friendly and thread-safe routine which returns data from shared library. In this case consequent calls specifically will overwrite the thread-local buffer, and this drawback is preferred over requiring the caller to explicitely free the returned data using a library provided "free_data()" function.</p>
  
  <pre><code>// For example as a return value:
  const char* text = MYLIB_get_foo_info();
  </code></pre>
  
  <p>The shared lib quarantees that the returned data is valid until the next call of the specific API function by the same thread that originally received the data from the API, and termination of the thread will invalidate (deallocate) it. The usage of the data is therefore in practice limited to a single-thread use, and should the API user desire to use the data with other threads or store it for later use it must take a value copy of it, in the API function caller thread. </p>
  
  <p>By definition in this particular case one can safely assume that nothing will invalidate the data during the caller reads it. This is exceptionally strong assumption indeed, which is based on the particular nature of the API and its very limited intented use. It is an option to later add another version of the API that does not require this assumption, if some need for it arises.</p>
  
  <p><strong>Question 2:</strong> Is it quaranteed that when the library user (application) thread terminate the TLS memory is deallocated at that moment? </p>
  
  <p>For example if the returned string is static thread_local std::string in the library.</p>
  
  <p>I have failed to find clear and direct answer this specific case (of using TLS from a shared library). </p>
  
  <p>Found two good articles about library API design, but these do not give any hints regarding TLS: </p>
  
  <ul>
  <li><a href="http://lucumr.pocoo.org/2013/8/18/beautiful-native-libraries/" rel="nofollow noreferrer">http://lucumr.pocoo.org/2013/8/18/beautiful-native-libraries/</a></li>
  <li><a href="https://anteru.net/blog/2016/05/01/3249/index.html" rel="nofollow noreferrer">https://anteru.net/blog/2016/05/01/3249/index.html</a></li>
  </ul>
  
  <p>Before C++11 for example with Windows one could use <code>TlsAlloc()</code> but one had to specifically check for library-caller threads created before loading the lib. </p>
  
  <p><strong>Question 3:</strong> Am I correct that with C++11 thread_local one does not have this kind of issues anymore? </p>
  
  <p><a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms686997(v=vs.85).aspx" rel="nofollow noreferrer">https://msdn.microsoft.com/en-us/library/windows/desktop/ms686997(v=vs.85).aspx</a></p>