jammy (3) gensio_unix_funcs_alloc.3.gz
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)