/* See LICENSE file for copyright and license details. */
#ifndef BUS_H
#define BUS_H
#ifndef _DEFAULT_SOURCE
# define _DEFAULT_SOURCE
#endif
#include <sys/types.h>
#include <time.h>
#if defined(__GNUC__)
# define BUS_COMPILER_GCC(X) X
#else
# define BUS_COMPILER_GCC(X) /* ignore */
#endif
/**
* Open the bus for reading only
*/
#define BUS_RDONLY 1
/**
* Open the bus for writing only
*/
#define BUS_WRONLY 0
/**
* Open the bus for both reading and writing only
*/
#define BUS_RDWR 0
/**
* Fail to create bus if its file already exists
*/
#define BUS_EXCL 2
/**
* Fail if interrupted
*/
#define BUS_INTR 4
/**
* Function shall fail with errno set to `EAGAIN`
* if the it would block and this flag is used
*/
#define BUS_NOWAIT 1
/**
* The number of bytes in storeable in the shared memory,
* note that this includes the NUL-termination.
* This means that message can be at most one byte smaller.
*/
#define BUS_MEMORY_SIZE 2048
/**
* Bus information
*/
typedef struct bus
{
/**
* The key for the semaphore array
*/
key_t key_sem;
/**
* The key for the shared memory
*/
key_t key_shm;
/**
* The ID of the semaphore array
*/
int sem_id;
/**
* The address of the shared memory
*/
char *message;
/**
* Non-zero if and only if `bus_poll` has not been
* called since the last `bus_poll_start`, or
* if `bus_poll` failed during reading
*/
int first_poll;
} bus_t;
/**
* Create a new bus
*
* @param file The pathname of the bus, `NULL` to create a random one
* @param flags `BUS_EXCL` (if `file` is not `NULL`) to fail if the file
* already exists, otherwise if the file exists, nothing
* will happen;
* `BUS_INTR` to fail if interrupted
* @param out_file Output parameter for the pathname of the bus
* @return 0 on success, -1 on error
*/
BUS_COMPILER_GCC(__attribute__((__warn_unused_result__)))
int bus_create(const char *restrict, int, char **restrict);
/**
* Remove a bus
*
* @param file The pathname of the bus
* @return 0 on success, -1 on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__)))
int bus_unlink(const char *);
/**
* Open an existing bus
*
* @param bus Bus information to fill
* @param file The filename of the bus
* @param flags `BUS_RDONLY`, `BUS_WRONLY` or `BUS_RDWR`,
* the value must not be negative
* @return 0 on success, -1 on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__, __warn_unused_result__)))
int bus_open(bus_t *restrict, const char *restrict, int);
/**
* Close a bus
*
* @param bus Bus information
* @return 0 on success, -1 on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__)))
int bus_close(bus_t *);
/**
* Broadcast a message on a bus
*
* @param bus Bus information
* @param message The message to write, may not be longer than
* `BUS_MEMORY_SIZE` including the NUL-termination
* @param flags `BUS_NOWAIT` if this function shall fail if
* another process is currently running this
* procedure
* @return 0 on success, -1 on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__, __warn_unused_result__)))
int bus_write(const bus_t *, const char *, int);
/**
* Broadcast a message on a bus
*
* @param bus Bus information
* @param message The message to write, may not be longer than
* `BUS_MEMORY_SIZE` including the NUL-termination
* @param timeout The time the operation shall fail with errno set
* to `EAGAIN` if not completed
* @param clockid The ID of the clock the `timeout` is measured with,
* it most be a predictable clock
* @return 0 on success, -1 on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__(1, 2), __warn_unused_result__)))
int bus_write_timed(const bus_t *, const char *, const struct timespec *, clockid_t);
/**
* Listen (in a loop, forever) for new message on a bus
*
* @param bus Bus information
* @param callback Function to call when a message is received, the
* (message, user_data) input parameters will be the read message and
* `user_data` from `bus_read`'s parameter with the
* same name. The message must have been parsed or
* copied when `callback` returns as it may be over
* overridden after that time. `callback` should
* return either of the the values:
* * 0: stop listening
* * 1: continue listening
* * -1: an error has occurred
* However, the function [`bus_read`] will invoke
* `callback` with `message` set to `NULL`one time
* directly after it has started listening on the
* bus. This is to the the program now it can safely
* continue with any action that requires that the
* programs is listening on the bus.
* @param user_data Parameter passed to `callback`
* @return 0 on success, -1 on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__(1, 2), __warn_unused_result__)))
int bus_read(const bus_t *restrict, int (*)(const char *, void *), void *);
/**
* Listen (in a loop, forever) for new message on a bus
*
* @param bus Bus information
* @param callback Function to call when a message is received, the
* (message, user_data) input parameters will be the read message and
* `user_data` from `bus_read`'s parameter with the
* same name. The message must have been parsed or
* copied when `callback` returns as it may be over
* overridden after that time. `callback` should
* return either of the the values:
* * 0: stop listening
* * 1: continue listening
* * -1: an error has occurred
* However, the function [`bus_read`] will invoke
* `callback` with `message` set to `NULL`one time
* directly after it has started listening on the
* bus. This is to the the program now it can safely
* continue with any action that requires that the
* programs is listening on the bus.
* @param user_data Parameter passed to `callback`
* @param timeout The time the operation shall fail with errno set
* to `EAGAIN` if not completed, note that the callback
* function may or may not have been called
* @param clockid The ID of the clock the `timeout` is measured with,
* it most be a predictable clock
* @return 0 on success, -1 on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__(1, 2), __warn_unused_result__)))
int bus_read_timed(const bus_t *restrict, int (*)(const char *, void *),
void *, const struct timespec *, clockid_t);
/**
* Announce that the thread is listening on the bus.
* This is required so the will does not miss any
* messages due to race conditions. Additionally,
* not calling this function will cause the bus the
* misbehave, is `bus_poll` is written to expect
* this function to have been called.
*
* @param bus Bus information
* @return 0 on success, -1 on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__, __warn_unused_result__)))
int bus_poll_start(bus_t *);
/**
* Announce that the thread has stopped listening on the bus.
* This is required so that the thread does not cause others
* to wait indefinitely.
*
* @param bus Bus information
* @return 0 on success, -1 on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__, __warn_unused_result__)))
int bus_poll_stop(const bus_t *);
/**
* Wait for a message to be broadcasted on the bus.
* The caller should make a copy of the received message,
* without freeing the original copy, and parse it in a
* separate thread. When the new thread has started be
* started, the caller of this function should then
* either call `bus_poll` again or `bus_poll_stop`.
*
* @param bus Bus information
* @param flags `BUS_NOWAIT` if the bus should fail and set `errno` to
* `EAGAIN` if there isn't already a message available on the bus
* @return The received message, `NULL` on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__, __warn_unused_result__)))
const char *bus_poll(bus_t *, int);
/**
* Wait for a message to be broadcasted on the bus.
* The caller should make a copy of the received message,
* without freeing the original copy, and parse it in a
* separate thread. When the new thread has started be
* started, the caller of this function should then
* either call `bus_poll_timed` again or `bus_poll_stop`.
*
* @param bus Bus information
* @param timeout The time the operation shall fail with errno set
* to `EAGAIN` if not completed
* @param clockid The ID of the clock the `timeout` is measured with,
* it most be a predictable clock
* @return The received message, `NULL` on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__(1), __warn_unused_result__)))
const char *bus_poll_timed(bus_t *, const struct timespec *, clockid_t);
/**
* Change the ownership of a bus
*
* `stat(2)` can be used of the bus's associated file to get the bus's ownership
*
* @param file The pathname of the bus
* @param owner The user ID of the bus's new owner
* @param group The group ID of the bus's new group
* @return 0 on success, -1 on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__, __warn_unused_result__)))
int bus_chown(const char *, uid_t, gid_t);
/**
* Change the permissions for a bus
*
* `stat(2)` can be used of the bus's associated file to get the bus's permissions
*
* @param file The pathname of the bus
* @param mode The permissions of the bus, any permission for a user implies
* full permissions for that user, except only the owner may
* edit the bus's associated file
* @return 0 on success, -1 on error
*/
BUS_COMPILER_GCC(__attribute__((__nonnull__, __warn_unused_result__)))
int bus_chmod(const char *, mode_t);
#endif
