lib/silcutil/silcschedule.h

   1 /****h* silcutil/silcschedule.h
   2  *
   3  * NAME
   4  *
   5  * silcschedule.h
   6  *
   7  * COPYRIGHT
   8  *
   9  * Author: Pekka Riikonen <priikone@silcnet.org>
  10  *
  11  * Copyright (C) 1998 - 2001 Pekka Riikonen
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  */
  24
  25 #ifndef SILCSCHEDULE_H
  26 #define SILCSCHEDULE_H
  27
  28 /****s* silcutil/SilcScheduleAPI/SilcSchedule
  29  *
  30  * NAME
  31  *
  32  *    typedef struct SilcScheduleStruct *SilcSchedule;
  33  *
  34  * DESCRIPTION
  35  *
  36  *    This context is the actual Scheduler and is allocated by
  37  *    the silc_schedule_init funtion.  The context is given as argument
  38  *    to all silc_schedule_* functions.  It must be freed by the
  39  *    silc_schedule_uninit function.
  40  *
  41  ***/
  42 typedef struct SilcScheduleStruct *SilcSchedule;
  43
  44 /* Prototypes */
  45
  46 /****f* silcutil/SilcScheduleAPI/silc_schedule_init
  47  *
  48  * SYNOPSIS
  49  *
  50  *    SilcSchedule silc_schedule_init(SilcTaskQueue *fd_queue,
  51  *                                    SilcTaskQueue *timeout_queue,
  52  *                                    SilcTaskQueue *generic_queue,
  53  *                                    int max_fd);
  54  *
  55  * DESCRIPTION
  56  *
  57  *    Initializes the scheduler. Sets the non-timeout task queue hook and
  58  *    the timeout task queue hook. This must be called before the scheduler
  59  *    is able to work. This will allocate the queue pointers if they are
  60  *    not allocated. Returns the scheduler context that must be freed by
  61  *    the silc_schedule_uninit function.
  62  *
  63  ***/
  64 SilcSchedule silc_schedule_init(SilcTaskQueue *fd_queue,
  65                                 SilcTaskQueue *timeout_queue,
  66                                 SilcTaskQueue *generic_queue,
  67                                 int max_fd);
  68
  69 /****f* silcutil/SilcScheduleAPI/silc_schedule_uninit
  70  *
  71  * SYNOPSIS
  72  *
  73  *    bool silc_schedule_uninit(SilcSchedule schedule);
  74  *
  75  * DESCRIPTION
  76  *
  77  *    Uninitializes the schedule. This is called when the program is ready
  78  *    to end. This removes all tasks and task queues. Returns FALSE if the
  79  *    scheduler could not be uninitialized. This happens when the scheduler
  80  *    is still valid and silc_schedule_stop has not been called.
  81  *
  82  ***/
  83 bool silc_schedule_uninit(SilcSchedule schedule);
  84
  85 /****f* silcutil/SilcScheduleAPI/silc_schedule_stop
  86  *
  87  * SYNOPSIS
  88  *
  89  *    void silc_schedule_stop(SilcSchedule schedule);
  90  *
  91  * DESCRIPTION
  92  *
  93  *    Stops the scheduler even if it is not supposed to be stopped yet.
  94  *    After calling this, one must call silc_schedule_uninit (after the
  95  *    silc_schedule has returned).
  96  *
  97  ***/
  98 void silc_schedule_stop(SilcSchedule schedule);
  99
 100 /****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd
 101  *
 102  * SYNOPSIS
 103  *
 104  *    void silc_schedule_set_listen_fd(SilcSchedule schedule,
 105  *                                     int fd, uint32 iomask);
 106  *
 107  * DESCRIPTION
 108  *
 109  *    Sets a file descriptor to be listened by the scheduler. One can
 110  *    call this directly if wanted. This can be called multiple times for
 111  *    one file descriptor to set different iomasks.
 112  *
 113  ***/
 114 void silc_schedule_set_listen_fd(SilcSchedule schedule, int fd, uint32 iomask);
 115
 116 /****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd
 117  *
 118  * SYNOPSIS
 119  *
 120  *    void silc_schedule_unset_listen_fd(SilcSchedule schedule, int fd);
 121  *
 122  * DESCRIPTION
 123  *
 124  *    Removes a file descriptor from listen list.  The file descriptor
 125  *    is not listened by the scheduler after this function.
 126  *
 127  ***/
 128 void silc_schedule_unset_listen_fd(SilcSchedule schedule, int fd);
 129
 130 /****f* silcutil/SilcScheduleAPI/silc_schedule
 131  *
 132  * SYNOPSIS
 133  *
 134  *    void silc_schedule(SilcSchedule schedule);
 135  *
 136  * DESCRIPTION
 137  *
 138  *    The SILC scheduler. This is actually the main routine in SILC programs.
 139  *    When this returns the program is to be ended. Before this function can
 140  *    be called, one must call silc_schedule_init function.
 141  *
 142  ***/
 143 void silc_schedule(SilcSchedule schedule);
 144
 145 /****f* silcutil/SilcScheduleAPI/silc_schedule
 146  *
 147  * SYNOPSIS
 148  *
 149  *    bool silc_schedule_one(SilcSchedule schedule, int block);
 150  *
 151  * DESCRIPTION
 152  *
 153  *    Same as the silc_schedule but runs the scheduler only one round
 154  *    and then returns.  This function is handy when the SILC scheduler
 155  *    is used inside some other external scheduler, for example.  If
 156  *    the `timeout_usecs' is positive a timeout will be added to the
 157  *    scheduler.  The function will not return in this timeout unless
 158  *    some other event occurs.
 159  *
 160  ***/
 161 bool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
 162
 163 #endif