libtextstyle: Document multithreading constraints.

* libtextstyle/gnulib-local/lib/term-ostream.oo.h (term_ostream_create):
Document the multithreading constraints that come from term-style-control.h.
* libtextstyle/gnulib-local/lib/term-styled-ostream.oo.h
(term_styled_ostream_create): Likewise.
* libtextstyle/doc/libtextstyle.texi (The term_ostream class,
The term_styled_ostream class): Likewise.

diff --git a/libtextstyle/doc/libtextstyle.texi b/libtextstyle/doc/libtextstyle.texi
index 8171d3b663809dfd280e0ac58cffccee114a933b..a71aee9f389631281a73380c4c83233252bca1c3 100644 (file)
--- a/libtextstyle/doc/libtextstyle.texi
+++ b/libtextstyle/doc/libtextstyle.texi
@@ -36,7 +36,7 @@
 This manual provides documentation for the GNU @code{libtextstyle} library.
 
 @copying
-Copyright (C) 2018-2024 Free Software Foundation, Inc.
+Copyright (C) 2018-2026 Free Software Foundation, Inc.
 
 This manual is free documentation.  It is dually licensed under the
 GNU FDL and the GNU GPL.  This means that you can redistribute this
@@ -68,7 +68,7 @@ A copy of the license is at @url{https://www.gnu.org/licenses/gpl.html}.
 @page
 @vskip 0pt plus 1filll
 @c @insertcopying
-Copyright (C) 2018-2024 Free Software Foundation, Inc.
+Copyright (C) 2018-2026 Free Software Foundation, Inc.
 
 This manual is free documentation.  It is dually licensed under the
 GNU FDL and the GNU GPL.  This means that you can redistribute this
@@ -1010,6 +1010,18 @@ The resulting stream will be line-buffered.
 
 Note: The resulting stream must be closed before @code{@var{fd}} can be
 closed.
+
+Multithreaded programs that use this function must obey two constraints:
+@itemize @bullet
+@item
+After creating a @code{term_ostream_t} in some thread, all output
+to the @code{@var{fd}} up to the moment where the stream gets closed must be done
+in the same thread.
+@item
+If at the moment of creation of a @code{term_ostream_t} the process is
+single-threaded, it @strong{must not} create additional threads until the stream
+gets closed.
+@end itemize
 @end deftypefn
 
 The class adds the following methods:
@@ -1225,6 +1237,18 @@ underlying tty.
 Note: The resulting stream must be closed before @code{@var{fd}} can be
 closed.
 
+Multithreaded programs that use this function must obey two constraints:
+@itemize @bullet
+@item
+After creating a @code{term_styled_ostream_t} in some thread, all output
+to the @code{@var{fd}} up to the moment where the stream gets closed must be done
+in the same thread.
+@item
+If at the moment of creation of a @code{term_styled_ostream_t} the process is
+single-threaded, it @strong{must not} create additional threads until the stream
+gets closed.
+@end itemize
+
 Returns @code{NULL} upon failure.
 @end deftypefn
 

diff --git a/libtextstyle/gnulib-local/lib/term-ostream.oo.h b/libtextstyle/gnulib-local/lib/term-ostream.oo.h
index e7025a34895d0d36bbc7b87801ea5ad84c9ca438..9792eace257729d5a25be225d921cce811059229 100644 (file)
--- a/libtextstyle/gnulib-local/lib/term-ostream.oo.h
+++ b/libtextstyle/gnulib-local/lib/term-ostream.oo.h
@@ -127,7 +127,14 @@ extern "C" {
    FILENAME is used only for error messages.
    TTY_CONTROL specifies the amount of control to take over the underlying tty.
    The resulting stream will be line-buffered.
-   Note that the resulting stream must be closed before FD can be closed.  */
+   Note that the resulting stream must be closed before FD can be closed.
+   Multithreaded programs that use this function must obey two constraints:
+     - After creating a term_ostream_t in some thread, all output
+       to the FD up to the moment where the stream gets closed must be done
+       in the same thread.
+     - If at the moment of creation of a term_ostream_t the process is
+       single-threaded, it MUST NOT create additional threads until the stream
+       gets closed.  */
 extern term_ostream_t
        term_ostream_create (int fd, const char *filename, ttyctl_t tty_control);
 

diff --git a/libtextstyle/gnulib-local/lib/term-styled-ostream.oo.h b/libtextstyle/gnulib-local/lib/term-styled-ostream.oo.h
index 54ec565c206ef1eb45272c47a2d4871b451b2da0..0ac8c83daf7e694c1a45754aaff33d19f0bb45ff 100644 (file)
--- a/libtextstyle/gnulib-local/lib/term-styled-ostream.oo.h
+++ b/libtextstyle/gnulib-local/lib/term-styled-ostream.oo.h
@@ -44,6 +44,13 @@ extern "C" {
    FILENAME is used only for error messages.
    TTY_CONTROL specifies the amount of control to take over the underlying tty.
    Note that the resulting stream must be closed before FD can be closed.
+   Multithreaded programs that use this function must obey two constraints:
+     - After creating a term_styled_ostream_t in some thread, all output
+       to the FD up to the moment where the stream gets closed must be done
+       in the same thread.
+     - If at the moment of creation of a term_styled_ostream_t the process is
+       single-threaded, it MUST NOT create additional threads until the stream
+       gets closed.
    Return NULL upon failure.  */
 extern term_styled_ostream_t
        term_styled_ostream_create (int fd, const char *filename,