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 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /*
  38  * A channel is an asynchronous I/O multiplexer supporting multiple parallel
  39  * readers and writers. A channel may be buffered (depending on its 'size'
  40  * attribute). Writing fails unless buffer space is available and reading
  41  * fails if no data is available.
  42  */
  43
  44 struct sdb_channel;
  45 typedef struct sdb_channel sdb_channel_t;
  46
  47 /*
  48  * sdb_channel_create:
  49  * Create a new channel for elements of size 'elem_size'. At most, 'size'
  50  * elements can be buffered in the channel (default: 1).
  51  *
  52  * Returns:
  53  *  - a channel object on success
  54  *  - a negative value else
  55  */
  56 sdb_channel_t *
  57 sdb_channel_create(size_t size, size_t elem_size);
  58
  59 /*
  60  * sdb_channel_destroy:
  61  * Removing all pending data and destroy the specified channel freeing its
  62  * memory.
  63  */
  64 void
  65 sdb_channel_destroy(sdb_channel_t *chan);
  66
  67 /*
  68  * sdb_channel_write:
  69  * Write an element to a channel. The memory pointed to by 'data' is copied to
  70  * the buffer based on the channel's element size.
  71  *
  72  * Returns:
  73  *  - 0 on success
  74  *  - a negative value else
  75  */
  76 int
  77 sdb_channel_write(sdb_channel_t *chan, const void *data);
  78
  79 /*
  80  * sdb_channel_read:
  81  * Read an element from a channel. The element is copied to the location
  82  * pointed to by 'data' which needs to be large enough to store a whole
  83  * element based on the channel's element size.
  84  *
  85  * Returns:
  86  *  - 0 on success
  87  *  - a negative value else
  88  */
  89 int
  90 sdb_channel_read(sdb_channel_t *chan, void *data);
  91
  92 #ifdef __cplusplus
  93 } /* extern "C" */
  94 #endif
  95
  96 #endif /* ! SDB_UTILS_CHANNEL_H */
  97
  98 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */
  99