Airframe Application Utilities
libairframe 2.12.0 API documentation

Data Structures | Macros | Typedefs | Enumerations | Functions
mio.h File Reference

Airframe Multiple I/O Support. More...

#include <airframe/autoinc.h>

Go to the source code of this file.

Data Structures

struct  _MIOSource
 MIO data source structure. More...
 
struct  _MIOSink
 MIO data sink structure. More...
 
struct  _MIOAppDriver
 An MIO application driver. More...
 

Macros

#define MIO_ERROR_DOMAIN   g_quark_from_string("airframeMIO")
 GError domain for MIO errors.
 
#define MIO_ERROR_MULTIPLE   1
 Multiple errors occurred. More...
 
#define MIO_ERROR_ARGUMENT   2
 Illegal argument. More...
 
#define MIO_ERROR_IO   3
 An unspecified I/O error occurred.
 
#define MIO_ERROR_CONN   4
 A connection error occurred; a connection could not be opened or bound.
 
#define MIO_ERROR_NOINPUT   5
 No input is presently available.
 
#define MIO_ERROR_LOCK   6
 Output path is locked.
 
#define MIO_ERROR_IMPL   7
 Requested function is not implemented in this build of Airframe.
 
#define MIO_F_CTL_ERROR   0x00000001
 MIO dispatch function control flag signaling a non-retryable error. More...
 
#define MIO_F_CTL_TRANSIENT   0x00000002
 MIO dispatch function control flag signaling a transient error. More...
 
#define MIO_F_CTL_SOURCECLOSE   0x00000004
 MIO dispatch function control flag signaling that the source should be closed. More...
 
#define MIO_F_CTL_SINKCLOSE   0x00000008
 MIO dispatch function control flag signaling that the sink should be closed. More...
 
#define MIO_F_CTL_TERMINATE   0x00000010
 MIO dispatch function control flag signaling that the application should terminate. More...
 
#define MIO_F_CTL_POLL   0x00000020
 MIO dispatch function control flag signaling that no input is available from the source, and the source cannot block waiting for new input. More...
 
#define MIO_F_CTL_MASK   0x0000003f
 MIO dispatch function control flag mask. More...
 
#define MIO_F_OPT_LOCK   0x00008000
 MIO option flag signaling locking should be used if available. More...
 
#define MIO_F_OPT_DAEMON   0x00004000
 MIO option flag signaling sources should operate in daemon mode. More...
 
#define MIO_F_OPT_SINKLINK   0x00002000
 MIO option flag signaling one-to-one mapping between source and sink. More...
 
#define MIO_F_OPT_MASK   0x0000ffc0
 MIO option flag mask. More...
 
#define mio_fd(_s_)   GPOINTER_TO_INT((_s_)->vsp)
 Convenience macro to get a source or sink's currently open file descriptor. More...
 
#define mio_fp(_s_)   ((FILE *)(_s_)->vsp)
 Convenience macro to get a source or sink's currently open file pointer. More...
 

Typedefs

typedef enum _MIOType MIOType
 Enumeration of low-level I/O object types MIOSource and MIOSink can manage.
 
typedef struct _MIOSource MIOSource
 An MIO data source. More...
 
typedef struct _MIOSink MIOSink
 An MIO data sink. More...
 
typedef gboolean(* MIOSourceFn) (MIOSource *source, uint32_t *flags, GError **err)
 An MIO source open/close function. More...
 
typedef gboolean(* MIOAppSourceFn) (MIOSource *source, void *vctx, uint32_t *flags, GError **err)
 An MIO source application-layer open/close function. More...
 
typedef void(* MIOSourceFreeFn) (MIOSource *source)
 An MIO source free function. More...
 
typedef gboolean(* MIOSinkFn) (MIOSource *source, MIOSink *sink, uint32_t *flags, GError **err)
 An MIO sink open/close function. More...
 
typedef void(* MIOSinkFreeFn) (MIOSink *sink)
 An MIO sink free function. More...
 
typedef gboolean(* MIOAppFn) (MIOSource *source, MIOSink *sink, void *vctx, uint32_t *flags, GError **err)
 An MIO sink application-layer open/close and record process function. More...
 
typedef struct _MIOAppDriver MIOAppDriver
 An MIO application driver. More...
 

Enumerations

enum  _MIOType {
  MIO_T_ANY = 0, MIO_T_APP = 1, MIO_T_NULL = 2, MIO_T_FD = 3,
  MIO_T_FP = 4, MIO_T_PCAP = 5, MIO_T_SOCK_DGRAM = 6, MIO_T_SOCK_STREAM = 7,
  MIO_T_SINKARRAY = 8, MIO_T_SOCK_TLS = 9
}
 Enumeration of low-level I/O object types MIOSource and MIOSink can manage. More...
 

Functions

gboolean mio_dispatch (MIOSource *source, MIOSink *sink, MIOAppDriver *app_drv, void *vctx, uint32_t *flags, GError **err)
 MIO primary dispatch function. More...
 
gboolean mio_dispatch_loop (MIOSource *source, MIOSink *sink, MIOAppDriver *app_drv, void *vctx, uint32_t flags, uint32_t polltime, uint32_t retrybase, uint32_t retrymax)
 MIO dispatch loop convenience function. More...
 
void mio_source_free (MIOSource *source)
 Frees an MIOSource by calling its source_free function. More...
 
void mio_sink_free (MIOSink *sink)
 Frees an MIOSink by calling its sink_free function. More...
 
gboolean mio_source_init_app (MIOSource *source, const char *spec, MIOType vsp_type, void *cfg, GError **err)
 Initialize an application-specific source. More...
 
gboolean mio_sink_init_app (MIOSink *sink, const char *spec, MIOType vsp_type, void *cfg, GError **err)
 Initialize an application-specific sink. More...
 

Detailed Description

Airframe Multiple I/O Support.

Supplies a framework for building applications that perform record-oriented processing on a wide variety of low-level input and output objects.

MIO applications read their input from an MIOSource and write it to an MIOSink. Sources and sinks are iterable; in other words, an application will generally have a single MIOSource which describes all the input it will read during its run, and which at any given time has a current source pointer, referring to the currently open file, socket, etc. MIOSource does not manage reading of bytes or records from the current source pointer; it simply hands this pointer (a file descriptor, file pointer, etc.) to the application and allows the application to handle its own low-level I/O. MIOSink works similarly.

Once an application has a source and a sink, it creates an MIOAppDriver containing five functions - one each to open and close the source, one each to open and close the sink, and one to process a single record from source to sink. These functions are called by mio_dispatch(), which is in turn called repeatedly by mio_dispatch_loop() to process all the records in each source described by the MIOSource. Application drivers may set flags (MIO_F_CTL constants) to control the closing of sinks and sources, the reporting of errors, and termination of the application.

Applications may create their own sources and sinks using the various initialization functions available in each source or sink's header file; however, it is more common to use the facilities in mio_config.h to allow the user to configure input and output.

Macro Definition Documentation

◆ MIO_ERROR_ARGUMENT

#define MIO_ERROR_ARGUMENT   2

Illegal argument.

The user supplied an illegal argument combination, or referred to an inaccessible or nonexistant path.

◆ MIO_ERROR_MULTIPLE

#define MIO_ERROR_MULTIPLE   1

Multiple errors occurred.

Usually occurs when attempt to clean up after an error fails itself. See the error message for detailed information.

◆ MIO_F_CTL_ERROR

#define MIO_F_CTL_ERROR   0x00000001

MIO dispatch function control flag signaling a non-retryable error.

This simply serves to differentiate error conditions from "normal" exception conditions. Set by low-level next, application open, or application process functions. These functions must also set MIO_F_SOURCECLOSE or MIO_F_SINKCLOSE if the source or sink must also be closed. Should be checked by the mio_dispatch() caller to detect non-retryable errors.

◆ MIO_F_CTL_MASK

#define MIO_F_CTL_MASK   0x0000003f

MIO dispatch function control flag mask.

mio_dispatch() clears each flag in this mask at the start of the call. Flags in this mask have a special meaning to mio_dispatch(), and may not be used by applications for their own purposes.

◆ MIO_F_CTL_POLL

#define MIO_F_CTL_POLL   0x00000020

MIO dispatch function control flag signaling that no input is available from the source, and the source cannot block waiting for new input.

mio_dispatch() caller should wait and try again. Set by low-level next function.

◆ MIO_F_CTL_SINKCLOSE

#define MIO_F_CTL_SINKCLOSE   0x00000008

MIO dispatch function control flag signaling that the sink should be closed.

Set on error by low-level next, application open, or application process functions, by mio_dispatch() if MIO_F_CTL_SOURCECLOSE and MIO_F_OPT_SINKLINK are set, or on other close condition (e.g. rotation delay timeout) by application process function. Causes mio_dispatch() to close the sink.

◆ MIO_F_CTL_SOURCECLOSE

#define MIO_F_CTL_SOURCECLOSE   0x00000004

MIO dispatch function control flag signaling that the source should be closed.

Set on error by low-level next, application open, or application process functions, or on EOF or other close condition by application process function. Causes mio_dispatch() to close the source.

◆ MIO_F_CTL_TERMINATE

#define MIO_F_CTL_TERMINATE   0x00000010

MIO dispatch function control flag signaling that the application should terminate.

Set by low-level next, application open, or application process functions.

◆ MIO_F_CTL_TRANSIENT

#define MIO_F_CTL_TRANSIENT   0x00000002

MIO dispatch function control flag signaling a transient error.

Transient errors can be retried; Applications may begin retry backoff on transient errors to avoid using resources with frequent retry. Set by low-level next, application open, or application process functions. These functions must also set MIO_F_SOURCECLOSE or MIO_F_SINKCLOSE if the source or sink must also be closed. Should by checked by mio_dispatch() caller to detect transient errors.

◆ MIO_F_OPT_DAEMON

#define MIO_F_OPT_DAEMON   0x00004000

MIO option flag signaling sources should operate in daemon mode.

Without this option, MIO low-level next will fail and set MIO_F_CTL_TERMINATE once all the available data covered by the input specifier has been processed once. With this option, the input specifier will be evaluated continually, and MIO itself will never terminate the application with MIO_F_CTL_TERMINATE; if no input is available, mio_dispatch will fail and set MIO_F_CTL_POLL instead. Set by mio_config_source() if daec_is_daemon() is TRUE.

◆ MIO_F_OPT_LOCK

#define MIO_F_OPT_LOCK   0x00008000

MIO option flag signaling locking should be used if available.

Locking is used to protect concurrent access to sources and sinks by multiple MIO-based applications. Set by mio_dispatch() caller, used by low-level source and sink next and close functions. Ignored by sources and sinks for which locking is not available or semantically meaningful; callers should be aware that setting this flag does NOT guarantee exclusive access among processes when using such sources and sinks. Set by mio_config_source() if –lock is present.

◆ MIO_F_OPT_MASK

#define MIO_F_OPT_MASK   0x0000ffc0

MIO option flag mask.

Flags in this mask are set by the application and undisturbed by dispatch operations. Flags in this mask have a special meaning to mio_dispatch(), and may not be used by applications for their own purposes.

◆ MIO_F_OPT_SINKLINK

#define MIO_F_OPT_SINKLINK   0x00002000

MIO option flag signaling one-to-one mapping between source and sink.

If this option is set, mio_dispatch() will set MIO_F_CTL_SINKCLOSE if MIO_F_CTL_SOURCECLOSE is set. Applications should set this flag if they are not managing multiple sink closure in their process function, and each input logically maps to a single output; however, mio_config_sink() may override this option for single file output.

◆ mio_fd

#define mio_fd (   _s_)    GPOINTER_TO_INT((_s_)->vsp)

Convenience macro to get a source or sink's currently open file descriptor.

Valid for MIO_T_FD and MIO_T_SOCK_* types.

◆ mio_fp

#define mio_fp (   _s_)    ((FILE *)(_s_)->vsp)

Convenience macro to get a source or sink's currently open file pointer.

Only valid if the source or sink's vsp_type is MIO_T_FP.

Typedef Documentation

◆ MIOAppDriver

typedef struct _MIOAppDriver MIOAppDriver

An MIO application driver.

Applications should pass one of these to mio_dispatch(); the functions are then called in the appropriate order by the mio_dispatch() run loop.

◆ MIOAppFn

typedef gboolean(* MIOAppFn) (MIOSource *source, MIOSink *sink, void *vctx, uint32_t *flags, GError **err)

An MIO sink application-layer open/close and record process function.

Passed into mio_dispatch() via an MIOAppDriver.

◆ MIOAppSourceFn

typedef gboolean(* MIOAppSourceFn) (MIOSource *source, void *vctx, uint32_t *flags, GError **err)

An MIO source application-layer open/close function.

Passed into mio_dispatch() via an MIOAppDriver.

◆ MIOSink

typedef struct _MIOSink MIOSink

An MIO data sink.

Represents a single, iterable, logical sink for data, such as a directory of output files, or an active socket. Create an MIOSink with one of the various mio_sink_init_*() functions, or with mio_config_sink().

◆ MIOSinkFn

typedef gboolean(* MIOSinkFn) (MIOSource *source, MIOSink *sink, uint32_t *flags, GError **err)

An MIO sink open/close function.

Used internally by MIOSink.

◆ MIOSinkFreeFn

typedef void(* MIOSinkFreeFn) (MIOSink *sink)

An MIO sink free function.

Used internally by MIOSink.

◆ MIOSource

typedef struct _MIOSource MIOSource

An MIO data source.

Represents a single, iterable, logical source of data, such as a directory of input files, or a passive socket. Create an MIOSource with one of the various mio_source_init_*() functions, or with mio_config_source().

◆ MIOSourceFn

typedef gboolean(* MIOSourceFn) (MIOSource *source, uint32_t *flags, GError **err)

An MIO source open/close function.

Used internally by MIOSource.

◆ MIOSourceFreeFn

typedef void(* MIOSourceFreeFn) (MIOSource *source)

An MIO source free function.

Used internally by MIOSource.

Enumeration Type Documentation

◆ _MIOType

enum _MIOType

Enumeration of low-level I/O object types MIOSource and MIOSink can manage.

Enumerator
MIO_T_ANY 

As an argument to a source init function, directs the source to use its default vsp_type.

Not valid as an actual vsp_type.

MIO_T_APP 

Source or sink pointer is managed by the application driver; used to keep the MIO dispatch loop but with no separation between application and low-level I/O (e.g., for AirDBC intergation)

MIO_T_NULL 

Source or sink pointer is NULL.

Used to suppress actual opening of sources, in cases where the application open/close routines must do so (e.g., external APIs which require file paths, not file descriptors or pointers.

MIO_T_FD 

Source or sink pointer is a non-socket file descriptor.

Used for unbuffered I/O, when an external API will provide its own buffering.

MIO_T_FP 

Source or sink pointer is a FILE pointer.

Used for buffered I/O, especially for files.

MIO_T_PCAP 

Source pointer is a pointer to a pcap_t libpcap context.

Used for packet capture from live interface or pcap dumpfile. Not valid on sinks; MIO does not support dumpfile output natively.

MIO_T_SOCK_DGRAM 

Source or sink pointer is a connect()ed datagram socket.

Use for reading or writing UDP packets.

MIO_T_SOCK_STREAM 

Source or sink pointer is a connect()ed stream socket.

Use for reading or writing TCP streams.

MIO_T_SINKARRAY 

Sink pointer is a pointer to an array of MIOSinks.

Use the mio_smc and mio_smn convenience macros in mio_sink_multi.h to access this array. Used by mio_sink_multi.h for output fanout support. Not valid on sources, for obvious reasons.

MIO_T_SOCK_TLS 

Source or sink pointer is a pointer to an SSL socket.

Used for TLSv1 or DTLS via OpenSSL.

Function Documentation

◆ mio_dispatch()

gboolean mio_dispatch ( MIOSource source,
MIOSink sink,
MIOAppDriver app_drv,
void *  vctx,
uint32_t *  flags,
GError **  err 
)

MIO primary dispatch function.

Processes a single record. Ensures that source and sink are available before processing the record, and ensures that source and sink are properly torn down afterward as necessary. Applications should probably use mio_dispatch_loop() instead, as it provides for such niceties as polling and retry.

Parameters
sourceAn MIOSource to get data from. mio_dispatch() may cause this source to close if it is open, and may cause this source to iterate if not.
sinkAn MIOSink to send data to. mio_dispatch() may cause this sink to close if it is open, and may cause this sink to iterate if not.
app_drvAn MIOAppDriver containing application functions to call source and sink open and close, and for actual record processing.
vctxApplication-level context passed to each of the functions in the MIOAppDriver.
flagsPointer to MIO dispatch flags (a bitwise union of MIO_F_* constants). These flags will be modified by mio_dispatch(); check the MIO_F_CTL_* flags after calling mio_dispatch to determine whether an error was transient, whether there was any input available, whether the application should terminate, and whether the source or sink were closed.
errA GError error description (out)
Returns
TRUE if a record was successfully processed, FALSE otherwise (setting error and flags).

◆ mio_dispatch_loop()

gboolean mio_dispatch_loop ( MIOSource source,
MIOSink sink,
MIOAppDriver app_drv,
void *  vctx,
uint32_t  flags,
uint32_t  polltime,
uint32_t  retrybase,
uint32_t  retrymax 
)

MIO dispatch loop convenience function.

Calls mio_dispatch() repeatedly, logging any errors that occur as warnings, until mio_dispatch sets MIO_F_CTL_TERMINATE to terminate the application. Automatically sleeps on no input. Automatically backs off on transient errors.

Parameters
sourceAn MIOSource to get data from. mio_dispatch() may cause this source to close if it is open, and may cause this source to iterate if not.
sinkAn MIOSink to send data to. mio_dispatch() may cause this sink to close if it is open, and may cause this sink to iterate if not.
app_drvAn MIOAppDriver containing application functions to call source and sink open and close, and for actual record processing.
vctxApplication-level context passed to each of the functions in the MIOAppDriver.
flagsPointer to MIO dispatch flags (a bitwise union of MIO_F_* constants). These flags will be modified by mio_dispatch().
polltimetime, in seconds, to delay on no input.
retrybasetime, in seconds, to delay on the first transient error. Each subsequent transient error doubles the delay up to the maximum.
retrymax

◆ mio_sink_free()

void mio_sink_free ( MIOSink sink)

Frees an MIOSink by calling its sink_free function.

Parameters
sinkMIOSink to free

◆ mio_sink_init_app()

gboolean mio_sink_init_app ( MIOSink sink,
const char *  spec,
MIOType  vsp_type,
void *  cfg,
GError **  err 
)

Initialize an application-specific sink.

The MIO facility will not do any low-level open or close; dispatch on this source will require the application driver to handle all the details of sink management.

Parameters
sinkpointer to MIOSink to initialize. This MIOSink will be overwritten.
specinput specifier to initialize MIOSink with. The application driver will use this to do its own low-level open.
vsp_typerequested sink pointer type, or MIO_T_ANY for default. Only the default, MIO_T_APP, is supported.
cfgpointer to configuration context. The application driver will use this to do its own low-level sink configuration.
errAn error description pointer.
Returns
TRUE if the MIOSink was successfully initialized.

◆ mio_source_free()

void mio_source_free ( MIOSource source)

Frees an MIOSource by calling its source_free function.

Parameters
sourceMIOSource to free

◆ mio_source_init_app()

gboolean mio_source_init_app ( MIOSource source,
const char *  spec,
MIOType  vsp_type,
void *  cfg,
GError **  err 
)

Initialize an application-specific source.

The MIO facility will not do any low-level open or close; dispatch on this source will require the application driver to handle all the details of source management.

Parameters
sourcepointer to MIOSource to initialize. This MIOSource will be overwritten.
specinput specifier to initialize MIOSource with. The application driver will use this to do its own low-level open.
vsp_typerequested source pointer type, or MIO_T_ANY for default. Only the default, MIO_T_APP, is supported.
cfgpointer to configuration context. The application driver will use this to do its own low-level source configuration.
errAn error description pointer.
Returns
TRUE if the MIOSource was successfully initialized.