NAME

NCURSES_WINDOW_CB, NCURSES_SCREEN_CB, get_escdelay, set_escdelay, set_tabsize, use_screen, use_window - curses support for multi-threaded applications

SYNOPSIS

#include <ncurses/curses.h>

/* data types */
typedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);
typedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);

int get_escdelay(void);
int set_escdelay(int ms);
int set_tabsize(int cols);

int use_screen(SCREEN *scr, NCURSES_SCREEN_CB func, void *data);
int use_window(WINDOW *win, NCURSES_WINDOW_CB func, void *data);

DESCRIPTION

The ncurses library can be configured to support multi-threaded applications in a rudimentary way. Such configuration produces a different set of libraries, named libncursest, for example, since doing so alters ncurses's application binary interface (ABI).

Instead of modifying the programming interface (API) to make ncurses functions expect an additional argument specifying a thread, the library adds functions, usable in any configuration, that hide the mutexes (mutual exclusion locks) needed to prevent concurrent access to variables shared by multiple threads of execution.

ncurses threading support requires the use of functions to access members of the WINDOW structure (see curs_opaque(3X)). It further makes functions of the common global variables COLORS, COLOR_PAIRS, COLS, ESCDELAY, LINES, TABSIZE, curscr, newscr, and ttytype, maintaining them as as read-only values in the SCREEN structure.

Even this is not enough to make an application using curses thread-safe. We would expect a multi-threaded application to have threads updating separate windows (on the same device), and separate screens (on different devices). Further, applications expect a few of the global variables to be writable. The functions described here address these special situations.

The ESCDELAY and TABSIZE global variables are modified by some applications. To modify them in any configuration, use the set_escdelay or set_tabsize functions. Other global variables are not modifiable. get_escdelay retrieves ESCDELAY's value.

The use_window and use_screen functions provide coarse-grained mutexes for their respective WINDOW and SCREEN parameters; they call a user-supplied function, pass it a data parameter, and return the value from the user-supplied function to the application.

RETURN VALUE

get_escdelay returns the value of ESCDELAY. set_escdelay and set_tabsize return ERR upon failure and OK upon successful completion. use_screen and use_window return the int returned by the user-supplied function they are called with.

NOTES

ncurses provides both a C function and a preprocessor macro for each function documented in this page.

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.

SEE ALSO

curses(3X), curs_opaque(3X), curs_variables(3X)