ulut/ul_evcbase.h

   1 /*******************************************************************
   2   uLan Utilities Library - C library of basic reusable constructions
   3
   4   ul_evcbase.h  - event connectors
   5
   6   (C) Copyright 2001-2003 by Pavel Pisa - Originator
   7
   8   The uLan utilities library can be used, copied and modified under
   9   next licenses
  10     - GPL - GNU General Public License
  11     - LGPL - GNU Lesser General Public License
  12     - MPL - Mozilla Public License
  13     - and other licenses added by project originators
  14   Code can be modified and re-distributed under any combination
  15   of the above listed licenses. If contributor does not agree with
  16   some of the licenses, he/she can delete appropriate line.
  17   Warning, if you delete all lines, you are not allowed to
  18   distribute source code and/or binaries utilizing code.
  19
  20   See files COPYING and README for details.
  21
  22  *******************************************************************/
  23
  24 #ifndef _UL_EVCBASE_H
  25 #define _UL_EVCBASE_H
  26
  27 #include <stdarg.h>
  28
  29 #include "ul_utdefs.h"
  30 #include "ul_list.h"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 struct evc_link;
  37 struct evc_tx_hub;
  38 struct evc_rx_hub;
  39
  40 typedef int evc_rx_fnc_t(void);
  41 typedef int evc_prop_fnc_t(struct evc_link *link, va_list args);
  42
  43 /**
  44  * struct evc_link - Event Connector Link
  45  * @src:        describes source of the event link, contains pointer
  46  *              to &evc_tx_hub_t and @peers links list
  47  * @dst:        determines destination of the event, it can be @standalone
  48  *              rx_fnc() function with with @context or &evc_tx_hub_t
  49  *              in the @multi case
  50  * @propagate:  pointer to the arguments propagation function,
  51  * @refcnt:     link reference counter
  52  * @recursive:  link can propagate could be invoked recursively,
  53  *              else recursive events are ignored by link
  54  * @blocked:    event propagation is blocked for the link,
  55  *              can be used by application
  56  * @ready:      link is ready and has purpose to live - it connects
  57  *              two active entities
  58  * @dead:       link is dead and cannot propagate events
  59  * @delete_pend: link is being deleted, but it is taken simultaneously,
  60  *              delete has to wait for finish of the propagate and to moving
  61  *              to the next link
  62  * @malloced:   link has been malloced and should be automatically freed
  63  *              when referenc counts drop to zero
  64  * @standalone: link is used for standalone function invocation
  65  * @tx_full_hub: @src points to the full hub structure
  66  * @rx_full_hub: @dst points to the full hub structure
  67  * @taken:      link is in middle of the propagation process
  68  *
  69  * The link delivers events from the source to the destination.
  70  * The link specific function propagate() is called for each link leading from
  71  * the hub activated by evc_tx_hub_emit() and evc_tx_hub_propagate().
  72  * The propagate function is responsible for parameters transformation before
  73  * invocation of standalone or destination hub rx_fnc() function.
  74  */
  75
  76 typedef struct evc_link {
  77   struct {
  78     ul_list_node_t peers;
  79     struct evc_tx_hub *hub;
  80   } src;
  81   union {
  82     struct {
  83       ul_list_node_t peers;
  84       struct evc_rx_hub *hub;
  85     } multi;
  86     struct {
  87       evc_rx_fnc_t *rx_fnc;
  88       void *context;
  89       void **weakptr;
  90     } standalone;
  91   } dst;
  92   evc_prop_fnc_t *propagate;
  93   int           refcnt;
  94   unsigned      recursive:1;
  95   unsigned      blocked:1;
  96   unsigned      ready:1;
  97   unsigned      dead:1;
  98   unsigned      delete_pend:1;
  99   unsigned      malloced:1;
 100   unsigned      standalone:1;
 101   unsigned      tx_full_hub:1;
 102   unsigned      rx_full_hub:1;
 103   short         taken;
 104 } evc_link_t;
 105
 106 /**
 107  * struct evc_tx_hub - Event Transmit Hub
 108  * @links:      list of links outgoing from the hub
 109  */
 110 typedef struct evc_tx_hub {
 111   ul_list_head_t links;
 112 } evc_tx_hub_t;
 113
 114 /**
 115  * struct evc_rx_hub -  Event Receiving Hub
 116  * @links:      list of links incoming to the hub
 117  * @rx_fnc:     function invoked when event arives
 118  * @context:    context for rx_fnc()
 119  */
 120 typedef struct evc_rx_hub {
 121   ul_list_head_t links;
 122   evc_rx_fnc_t *rx_fnc;
 123   void *context;
 124 } evc_rx_hub_t;
 125
 126 evc_link_t *evc_link_new(void);
 127 evc_link_t *evc_link_new_standalone(evc_rx_fnc_t *rx_fnc, void *context);
 128 int evc_link_init(evc_link_t *link);
 129 int evc_link_init_standalone(evc_link_t *link, evc_rx_fnc_t *rx_fnc,
 130                      void *context);
 131 int evc_link_connect(evc_link_t *link, evc_tx_hub_t *src, evc_rx_hub_t *dst,
 132                      evc_prop_fnc_t *prop);
 133 int evc_link_connect_standalone(evc_link_t *link, evc_tx_hub_t *src,
 134            evc_prop_fnc_t *prop);
 135 int evc_link_delete(evc_link_t *link);
 136 void evc_link_dispose(evc_link_t *link);
 137
 138 int evc_tx_hub_init(evc_tx_hub_t *hub);
 139 void evc_tx_hub_done(evc_tx_hub_t *hub);
 140 void evc_tx_hub_propagate(evc_tx_hub_t *hub, va_list args);
 141 void evc_tx_hub_emit(evc_tx_hub_t *hub, ...);
 142 int evc_tx_hub_eol_weakptr(evc_tx_hub_t *hub, void **weakptr);
 143
 144 int evc_rx_hub_init(evc_rx_hub_t *hub, evc_rx_fnc_t *rx_fnc, void *context);
 145 void evc_rx_hub_done(evc_rx_hub_t *hub);
 146 void evc_rx_hub_disconnect_all(evc_rx_hub_t *hub);
 147
 148 int evc_link_propagate_i_p_l(evc_link_t *link, va_list args);
 149
 150 /**
 151  * evc_link_inc_refcnt - Increment Link Reference Count
 152  * @link:       pointer to link
 153  */
 154 static inline
 155 void evc_link_inc_refcnt(evc_link_t *link)
 156 {
 157   if(!link) return;
 158   if(link->refcnt >= 0) link->refcnt++;
 159 }
 160
 161 /**
 162  * evc_link_dec_refcnt - Decrement Link Reference Count
 163  * @link:       pointer to link
 164  *
 165  * if the link reference count drops to 0, link is deleted
 166  * from hubs by evc_link_dispose() function and if @malloced
 167  * is sed, link memory is disposed by free().
 168  * Special handlink can be achieved if propagate() returns non-zero
 169  * value if called with @ded link.
 170  */
 171 static inline
 172 void evc_link_dec_refcnt(evc_link_t *link)
 173 {
 174   if(!link) return;
 175   if(link->refcnt > 0) link->refcnt--;
 176   if(!link->refcnt) evc_link_dispose(link);
 177 }
 178
 179 #ifdef __cplusplus
 180 } /* extern "C"*/
 181 #endif
 182
 183
 184 #endif /* _UL_EVCBASE_H */