git.meshlink.io Git - catta/blob - include/catta/thread-watch.h

   1 #ifndef foothreadedwatchhfoo
   2 #define foothreadedwatchhfoo
   3
   4 /***
   5   This file is part of catta.
   6
   7   catta is free software; you can redistribute it and/or modify it
   8   under the terms of the GNU Lesser General Public License as
   9   published by the Free Software Foundation; either version 2.1 of the
  10   License, or (at your option) any later version.
  11
  12   catta is distributed in the hope that it will be useful, but WITHOUT
  13   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14   or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
  15   Public License for more details.
  16
  17   You should have received a copy of the GNU Lesser General Public
  18   License along with catta; if not, write to the Free Software
  19   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  20   USA.
  21 ***/
  22
  23 /** \file thread-watch.h Threaded poll() based main loop implementation */
  24
  25 #include <sys/poll.h>
  26 #include <catta/cdecl.h>
  27 #include <catta/watch.h>
  28
  29 CATTA_C_DECL_BEGIN
  30
  31 /** A main loop object that runs an CattaSimplePoll in its own thread. \since 0.6.4 */
  32 typedef struct CattaThreadedPoll CattaThreadedPoll;
  33
  34 /** Create a new event loop object. This will allocate the internal
  35  * CattaSimplePoll, but will not start the helper thread. \since 0.6.4 */
  36 CattaThreadedPoll *catta_threaded_poll_new(void);
  37
  38 /** Free an event loop object. This will stop the associated event loop
  39  * thread (if it is running). \since 0.6.4 */
  40 void catta_threaded_poll_free(CattaThreadedPoll *p);
  41
  42 /** Return the abstracted poll API object for this event loop
  43  * object. The will return the same pointer each time it is
  44  * called. \since 0.6.4 */
  45 const CattaPoll* catta_threaded_poll_get(CattaThreadedPoll *p);
  46
  47 /** Start the event loop helper thread. After the thread has started
  48  * you must make sure to access the event loop object
  49  * (CattaThreadedPoll, CattaPoll and all its associated objects)
  50  * synchronized, i.e. with proper locking. You may want to use
  51  * catta_threaded_poll_lock()/catta_threaded_poll_unlock() for this,
  52  * which will lock the the entire event loop. Please note that event
  53  * loop callback functions are called from the event loop helper thread
  54  * with that lock held, i.e. catta_threaded_poll_lock() calls are not
  55  * required from event callbacks. \since 0.6.4 */
  56 int catta_threaded_poll_start(CattaThreadedPoll *p);
  57
  58 /** Request that the event loop quits and the associated thread
  59  stops. Call this from outside the helper thread if you want to shut
  60  it down. \since 0.6.4 */
  61 int catta_threaded_poll_stop(CattaThreadedPoll *p);
  62
  63 /** Request that the event loop quits and the associated thread
  64  stops. Call this from inside the helper thread if you want to shut it
  65  down. \since 0.6.4  */
  66 void catta_threaded_poll_quit(CattaThreadedPoll *p);
  67
  68 /** Lock the main loop object. Use this if you want to access the event
  69  * loop objects (such as creating a new event source) from anything
  70  * else but the event loop helper thread, i.e. from anything else but event
  71  * loop callbacks \since 0.6.4  */
  72 void catta_threaded_poll_lock(CattaThreadedPoll *p);
  73
  74 /** Unlock the event loop object, use this as counterpart to
  75  * catta_threaded_poll_lock() \since 0.6.4 */
  76 void catta_threaded_poll_unlock(CattaThreadedPoll *p);
  77
  78 CATTA_C_DECL_END
  79
  80 #endif