src/include/utils/channel.h

   1 /*
   2  * SysDB - src/include/utils/channel.h
   3  * Copyright (C) 2013 Sebastian 'tokkee' Harl <sh@tokkee.org>
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  * 2. Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the distribution.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  16  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
  19  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  20  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 #ifndef SDB_UTILS_CHANNEL_H
  29 #define SDB_UTILS_CHANNEL_H 1
  30
  31 #include "core/object.h"
  32
  33 #include <sys/time.h>
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 /*
  40  * A channel is an asynchronous I/O multiplexer supporting multiple parallel
  41  * readers and writers. A channel may be buffered (depending on its 'size'
  42  * attribute). Writing fails unless buffer space is available and reading
  43  * fails if no data is available.
  44  */
  45
  46 struct sdb_channel;
  47 typedef struct sdb_channel sdb_channel_t;
  48
  49 /*
  50  * sdb_channel_create:
  51  * Create a new channel for elements of size 'elem_size'. At most, 'size'
  52  * elements can be buffered in the channel (default: 1).
  53  *
  54  * Returns:
  55  *  - a channel object on success
  56  *  - a negative value else
  57  */
  58 sdb_channel_t *
  59 sdb_channel_create(size_t size, size_t elem_size);
  60
  61 /*
  62  * sdb_channel_destroy:
  63  * Removing all pending data and destroy the specified channel freeing its
  64  * memory.
  65  */
  66 void
  67 sdb_channel_destroy(sdb_channel_t *chan);
  68
  69 /*
  70  * sdb_channel_write:
  71  * Write an element to a channel. The memory pointed to by 'data' is copied to
  72  * the buffer based on the channel's element size.
  73  *
  74  * Returns:
  75  *  - 0 on success
  76  *  - a negative value else
  77  */
  78 int
  79 sdb_channel_write(sdb_channel_t *chan, const void *data);
  80
  81 /*
  82  * sdb_channel_read:
  83  * Read an element from a channel. The element is copied to the location
  84  * pointed to by 'data' which needs to be large enough to store a whole
  85  * element based on the channel's element size.
  86  *
  87  * Returns:
  88  *  - 0 on success
  89  *  - a negative value else
  90  */
  91 int
  92 sdb_channel_read(sdb_channel_t *chan, void *data);
  93
  94 /*
  95  * sdb_channel_select:
  96  * Wait for a channel to become "ready" for I/O. A channel is considered ready
  97  * if it is possible to perform the corresponding I/O operation successfully
  98  * *in some thread*. In case 'wantread' or 'read_data' is non-NULL, wait for
  99  * data to be available in the channel for reading. In case 'wantwrite' or
 100  * 'write_data' is non-NULL, wait for buffer space to be available for writing
 101  * to the channel. If non-NULL, the value pointed to by the 'want...'
 102  * arguments will be "true" iff the respective operation is ready. If the
 103  * '..._data' arguments are non-NULL, the respective operation is executed
 104  * atomically once the channel is ready for it. If 'abstime' is specified, the
 105  * operation will time out with an error if the specified absolute time has
 106  * passed.
 107  */
 108 int
 109 sdb_channel_select(sdb_channel_t *chan, int *wantread, void *read_data,
 110                 int *wantwrite, void *write_data, const struct timespec *timeout);
 111
 112 #ifdef __cplusplus
 113 } /* extern "C" */
 114 #endif
 115
 116 #endif /* ! SDB_UTILS_CHANNEL_H */
 117
 118 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */
 119