From 7d1ebc2583ca6b4eabab56814ab78c9b3fa09adc Mon Sep 17 00:00:00 2001 From: joq Date: Tue, 16 Sep 2003 21:49:49 +0000 Subject: [PATCH] readability improvements; removed _ANNOTATED_DRIVER_DECLARATION_; no binary changes git-svn-id: svn+ssh://jackaudio.org/trunk/jack@499 0c269be4-1314-0410-8aa9-9f06e86f4224 --- jack/driver.h | 92 +++++++++++++++++++++++++-------------------------- 1 file changed, 45 insertions(+), 47 deletions(-) diff --git a/jack/driver.h b/jack/driver.h index 5aeba7b..6b0353b 100644 --- a/jack/driver.h +++ b/jack/driver.h @@ -46,14 +46,21 @@ typedef struct { struct _jack_engine; struct _jack_driver; -typedef int (*JackDriverAttachFunction)(struct _jack_driver *, struct _jack_engine *); -typedef int (*JackDriverDetachFunction)(struct _jack_driver *, struct _jack_engine *); -typedef int (*JackDriverReadFunction)(struct _jack_driver *, jack_nframes_t nframes); -typedef int (*JackDriverWriteFunction)(struct _jack_driver *, jack_nframes_t nframes); -typedef int (*JackDriverNullCycleFunction)(struct _jack_driver *, jack_nframes_t nframes); +typedef int (*JackDriverAttachFunction)(struct _jack_driver *, + struct _jack_engine *); +typedef int (*JackDriverDetachFunction)(struct _jack_driver *, + struct _jack_engine *); +typedef int (*JackDriverReadFunction)(struct _jack_driver *, + jack_nframes_t nframes); +typedef int (*JackDriverWriteFunction)(struct _jack_driver *, + jack_nframes_t nframes); +typedef int (*JackDriverNullCycleFunction)(struct _jack_driver *, + jack_nframes_t nframes); typedef int (*JackDriverStopFunction)(struct _jack_driver *); typedef int (*JackDriverStartFunction)(struct _jack_driver *); -typedef jack_nframes_t (*JackDriverWaitFunction)(struct _jack_driver *, int fd, int *status, float *delayed_usecs); +typedef jack_nframes_t (*JackDriverWaitFunction)(struct _jack_driver *, + int fd, int *status, + float *delayed_usecs); /* Call sequence summary: @@ -69,59 +76,59 @@ typedef jack_nframes_t (*JackDriverWaitFunction)(struct _jack_driver *, int fd, } 5) engine stops driver 6) engine detaches from driver - 7) engine calls driver `finish' routine, if any + 7) engine calls driver `finish' routine - note that stop/start may be called multiple times in the event of an + Note that stop/start may be called multiple times in the event of an error return from the `wait' function. */ -#ifdef _ANNOTATED_DRIVER_DECLARATION_ -#define JACK_DRIVER_DECL +typedef struct _jack_driver { -/* the driver should set this to be the interval it expects to elapse +/* The _jack_driver structure fields are included at the beginning of + each driver-specific structure using the JACK_DRIVER_DECL macro, + which is defined below. The comments that follow describe each + common field. + + The driver should set this to be the interval it expects to elapse between returning from the `wait' function. if set to zero, it implies that the driver does not expect regular periodic wakeups. - */ + jack_time_t period_usecs; -/* the driver should set this within its "wait" function to indicate + The driver should set this within its "wait" function to indicate the UST of the most recent determination that the engine cycle should run. it should not be set if the "extra_fd" argument of the wait function is set to a non-zero value. - */ + jack_time_t last_wait_ust; -/* this is not used by the driver. it should not be written to or + This is not used by the driver. it should not be written to or modified in any way - */ void *handle; -/* this should perform any cleanup associated with the driver. it will + This should perform any cleanup associated with the driver. it will be called when jack server process decides to get rid of the driver. in some systems, it may not be called at all, so the driver should never rely on a call to this. it can set it to NULL if it has nothing do do. - */ - void (*finish)(struct _jack_driver *);\ + void (*finish)(struct _jack_driver *); -/* the JACK engine will call this when it wishes to attach itself to + The JACK engine will call this when it wishes to attach itself to the driver. the engine will pass a pointer to itself, which the driver may use in anyway it wishes to. the driver may assume that this is the same engine object that will make `wait' calls until a `detach' call is made. - */ - JackDriverAttachFunction attach; \ + JackDriverAttachFunction attach; -/* the JACK engine will call this when it is finished using a driver. - */ + The JACK engine will call this when it is finished using a driver. - JackDriverDetachFunction detach; \ + JackDriverDetachFunction detach; -/* the JACK engine will call this when it wants to wait until the + The JACK engine will call this when it wants to wait until the driver decides that its time to process some data. the driver returns a count of the number of audioframes that can be processed. @@ -140,53 +147,48 @@ typedef jack_nframes_t (*JackDriverWaitFunction)(struct _jack_driver *, int fd, in this variable. the engine will use this to decide if it plans to continue execution. - */ - JackDriverWaitFunction wait; -/* the JACK engine will call this to ask the driver to move + The JACK engine will call this to ask the driver to move data from its inputs to its output port buffers. it should return 0 to indicate successful completion, negative otherwise. - this function will always be called after the wait function (above). -*/ + This function will always be called after the wait function (above). JackDriverReadFunction read; -/* the JACK engine will call this to ask the driver to move + The JACK engine will call this to ask the driver to move data from its input port buffers to its outputs. it should return 0 to indicate successful completion, negative otherwise. this function will always be called after the read function (above). -*/ + JackDriverWriteFunction write; -/* the JACK engine will call this after the wait function (above) has + The JACK engine will call this after the wait function (above) has been called, but for some reason the engine is unable to execute a full "cycle". the driver should do whatever is necessary to keep itself running correctly, but cannot reference ports or other JACK data structures in any way. -*/ JackDriverNullCycleFunction null_cycle; -/* the engine will call this when it plans to stop calling the `wait' + The engine will call this when it plans to stop calling the `wait' function for some period of time. the driver should take appropriate steps to handle this (possibly no steps at all) - */ - JackDriverStopFunction stop; \ + JackDriverStopFunction stop; -/* the engine will call this to let the driver know that it plans + The engine will call this to let the driver know that it plans to start calling the `wait' function on a regular basis. the driver should take any appropriate steps to handle this (possibly no steps at all) - */ - + JackDriverStartFunction start; -#else +*/ +/* define the fields here... */ #define JACK_DRIVER_DECL \ jack_time_t period_usecs; \ jack_time_t last_wait_ust; \ @@ -201,11 +203,7 @@ typedef jack_nframes_t (*JackDriverWaitFunction)(struct _jack_driver *, int fd, JackDriverStopFunction stop; \ JackDriverStartFunction start; -#endif /* _ANNOTATED_DRIVER_DECLARATION_ */ - -typedef struct _jack_driver { - - JACK_DRIVER_DECL + JACK_DRIVER_DECL /* expand the macro */ } jack_driver_t;