X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_threads.3x;fp=man%2Fcurs_threads.3x;h=de7714bb01bc45705253875e4e3c8a4d27e1418e;hb=25358bc041a5566ce2de4c9c792837e552b35671;hp=0000000000000000000000000000000000000000;hpb=c4d90db4f4e50bb8a971955ce4812262da4a50bc;p=ncurses.git

diff --git a/man/curs_threads.3x b/man/curs_threads.3x
new file mode 100644
index 00000000..de7714bb
--- /dev/null
+++ b/man/curs_threads.3x
@@ -0,0 +1,113 @@
+.\"***************************************************************************
+.\" Copyright (c) 2008 Free Software Foundation, Inc.                        *
+.\"                                                                          *
+.\" Permission is hereby granted, free of charge, to any person obtaining a  *
+.\" copy of this software and associated documentation files (the            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: curs_threads.3x,v 1.4 2008/01/19 23:29:24 tom Exp $
+.TH curs_threads 3X ""
+.na
+.hy 0
+.SH NAME
+\fBuse_screen\fR,
+\fBuse_window\fR - \fBcurses\fR thread support
+.ad
+.hy
+.SH SYNOPSIS
+\fB#include <curses.h>\fR
+.sp
+\fBtypedef int (*NCURSES_CALLBACK)(WINDOW *, void *);\fR
+.br
+\fBint set_escdelay(int size);\fR
+.br
+\fBint set_tabsize(int size);\fR
+.br
+\fBint use_screen(SCREEN *scr, NCURSES_CALLBACK func, void *data);\fR
+.br
+\fBint use_window(WINDOW *win, NCURSES_CALLBACK func, void *data);\fR
+.br
+.SH DESCRIPTION
+This implementation can be configured to provide rudimentary support
+for multi-threaded applications.
+This makes a different set of libraries, e.g., \fIlibncursest\fP since
+the binary interfaces are different.
+.PP
+Rather than modify the interfaces to pass a thread specifier to
+each function, it adds a few functions which can be used in any
+configuration which hide the mutex's needed to prevent concurrent
+use of the global variables when configured for threading.
+.PP
+In addition to forcing access to members of the \fBWINDOW\fP structure
+to be via functions (see \fBcurs_opaque\fP(3x)),
+it makes functions of the common global variables,
+e.g.,
+COLORS,
+COLOR_PAIRS,
+COLS,
+ESCDELAY,
+LINES,
+TABSIZE
+curscr,
+newscr and
+ttytype.
+Those variables are maintained as read-only values, stored in the \fBSCREEN\fP
+structure.
+.PP
+Even this is not enough to make a thread-safe application using curses.
+A multi-threaded application would be expected to have threads updating
+separate windows (within the same device),
+or updating on separate screens (on different devices).
+Also, a few of the global variables are considered writable by some
+applications.
+The functions described here address these special situations.
+.PP
+The ESCDELAY and TABSIZE global variables are modified by some applications.
+To modify them in any configuration,
+use the \fBset_escdelay\fP or \fBset_tabsize\fP functions.
+Other global variables are not modifiable.
+.PP
+The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse
+granularity mutexes for their respective \fBWINDOW\fP and \fBSCREEN\fP
+parameters, and call a user-supplied function,
+passing it a \fIdata\fP parameter,
+and returning the value from the user-supplied function to the application.
+.SH RETURN VALUE
+These functions all return TRUE or FALSE, except as noted.
+.SH NOTES
+Both a macro and a function are provided for each name.
+.SH PORTABILITY
+These routines are specific to ncurses.
+They were not supported on Version 7, BSD or System V implementations.
+It is recommended that any code depending on ncurses extensions
+be conditioned using NCURSES_VERSION.
+.SH SEE ALSO
+\fBcurses\fR(3X),
+\fBcurs_opaque\fR(3X)
+.\"#
+.\"# The following sets edit modes for GNU EMACS
+.\"# Local Variables:
+.\"# mode:nroff
+.\"# fill-column:79
+.\"# End: