Provided by: libgensio-dev_2.3.5-1build2_amd64 
NAME
gensio_os_funcs - Abstraction for some operating system functions used by the gensio
library
SYNOPSIS
#include <gensio/gensio_os_funcs.h>
struct gensio_os_funcs {}
int gensio_default_os_hnd(int wake_sig, struct gensio_os_funcs **o)
int gensio_unix_funcs_alloc(struct selector_s *sel, int wake_sig,
struct gensio_os_funcs **o)
int gensio_win_funcs_alloc(struct gensio_os_funcs **o)
int gensio_os_proc_setup(struct gensio_os_funcs *o,
struct gensio_os_proc_data **data)
void gensio_os_proc_cleanup(struct gensio_os_proc_data *data);
sigset_t *gensio_os_proc_unix_get_wait_sigset(
struct gensio_os_proc_data *data);
int gensio_os_new_thread(struct gensio_os_funcs *o,
void (*start_func)(void *data), void *data,
struct gensio_thread **thread_id);
int gensio_os_wait_thread(struct gensio_thread *thread_id);
DESCRIPTION
This structure provides an abstraction for the gensio library that lets it work with
various event libraries. It provides the following basic functions:
memory allocation - Allocate and free memory.
mutexes - Provide mutual exclusion.
file handler callbacks - Allows file descriptors to be monitored
and report when I/O is ready on them.
timers - Call callbacks after a certain amount of time has elapsed.
runners - Run a function in a new execution context. Calling callbacks
straight from user functions can result in deadlocks, this provides a way to call
callbacks from a separate context.
waiters - Wait for operations to occur while running timers, runners
and watching for file descriptors.
logging - Allow the gensio library to generate logs to report issues.
These are documented in the include file.
The basic issue is that there are various event handling libraries (Tcl/Tk, glib, Xlib,
custom ones, etc.) and you may want to integrate the gensio library with one of these.
Even though it's a bit of a pain to have to pass one of these around, it adds needed
flexibility.
gensio_default_os_hnd provides a way to allocate a default OS function handler for the
platform. The same value will be returned each time, only one is created. You should
generally use this one unless you have a special need as documented above.
The wait_sig parameter usage on Windows is unused. For Unix systems, this signal is used
to signal other processes that may be waiting that they need to wake up. This is used to
wake up a process waiting on a waiter, and it's used to signal all waiting processes if a
timer is added that is sooner than any other timer so they can adjust their waits.
If you are running your program in a single thread, you can safely pass zero into this
parameter.
If your app is multi-threaded (or, more accurately, if your app has multiple threads that
are making gensio calls) you must pass a valid signal into this, and you must set up an
empty handler for this signal, and the signal must be blocked in all threads that call a
wait function. You should not use this signal for anything else. The function that
allocates a signal handler will block the signal in the calling thread, and that sigmask
is passed on to other threads it creates. But if you have allocated threads before
allocating the os funcs, you must make sure those other threads have this signal blocked.
Also, if you pass in a different value to gensio_default_os_hnd than the first one you
passed in, it will return GE_INVAL. You can pass in different values to
gensio_unix_funcs_alloc calls, and it will use them, but there's not much value in this.
The os funcs for Unix can share a signal handler. And there's not much value is multiple
OS funcs, anyway.
gensio_unix_funcs_alloc and gensio_win_funcs_alloc Allocate the normal os funcs for Unix
and Windows based systems, respectively.
The sel parameter for Unix allows you to create your own selector object and pass it to
the OS handler. Passing in NULL will cause it to allocate it's own selector object. See
the selector.h include file for details.
The wake_sig value is a signal for use by the OS functions for internal communication
between threads. If you are running a multi-threaded application, you must provide a
valid signal that you don't use for any other purpose, generally SIGUSR1 or SIGUSR2.
The gensio_os_proc_setup function does all the standard setup for a process. You should
almost certainly use this function. On Windows this isn't anything (though that may
change in the future, so you should still do it), but on Unix it does all the signal
handling setup, so you don't have to do all the things mentioned above. This will block
SIGPIPE (because those come in when connections die and most applications don't care),
SIGCHLD (those come in for stdio and pty gensios), and the wake_sig if that is set. It
also install signal handlers for SIGCHLD and the wake_sig (if set) and sets up a signal
mask.
If you use the wait_intr_sigmask OS function, you must pass the proc_data value returned
by gensio_os_proc_setup into that. If you want to modify the wait signal mask, you can
use gensio_os_proc_unix_get_wait_sigset to fetch it and modify it.
The gensio_os_proc_cleanup function undoes all the changes gensio_os_proc_setup does. On
Unix it restores the signal mask and signal handlers it sets to their previous values.
The gensio_os_new_thread function starts a new thread at start_func passing in the given
data value. It returns a thread_id that you must pass into the wait function. This is
just basic generic threads, you can use your OS functions if you need more control over
the threads. If you use threads, make sure to see the notes above about setting up for
them properly.
The gensio_os_wait_thread waits for a thread to stop. Note that it does not cause the
thread to stop, it waits for it to stop. You have to cause the thread to stop yourself.
RETURN VALUES
gensio_default_os_hnd returns a standard gensio error.
SEE ALSO
gensio_set_log_mask(3), gensio_get_log_mask(3), gensio_log_level_to_str(3), gensio(5),
gensio_err(3)
23 Feb 2019 gensio_os_funcs(3)