libphobos/libdruntime/core/sys/posix/mqueue.d

/**
 * D header file for Posix Message Queues
 *
 * Defines external functions required to manage Posix Message Queues
 *
 * mq_open(3)          open a message queue
 * mq_close(3)         close a message queue
 * mq_unlink(3)        remove a message queue
 * mq_send(3)          send a message
 * mq_receive(3)       receive a message
 * mq_timedsend(3)     send a message with a timeout (linux specific)
 * mq_timedreceive(3)  receive a message with a timeout (linux specific)
 * mq_getattr(3)       get message queue attributes
 * mq_setattr(3)       set message queue attributes
 * mq_notify(3)        register asynchronous notify
 *
 * Copyright: Copyright (c) 2016 sociomantic labs. All rights reserved
 * License:   $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0).
 * Authors:   Andreas Bok Andersen, Mathias Lang
 * Standards: POSIX.1-2001.
 * See_Also:  $(HTTP pubs.opengroup.org/onlinepubs/9699919799/basedefs/mqueue.h.html, Standard)
 * Source: $(DRUNTIMESRC core/sys/posix/mqueue.d)
 */
module core.sys.posix.mqueue;

import core.sys.posix.config;
import core.sys.posix.signal;
import core.sys.posix.time;

version (Posix):
extern (C):
@nogc nothrow:

version (CRuntime_Glibc)
{
    /// Message queue descriptor.
    alias mqd_t = int;

    /**
     * Used in getting and setting the attributes of a message queue.
     */
    struct mq_attr
    {
        /// Message queue flags.
        c_long mq_flags;
        /// Maximum number of messages.
        c_long mq_maxmsg;
        /// Maximum message size.
        c_long mq_msgsize;
        /// Number of messages currently queued.
        c_long mq_curmsgs;
    }


    /**
     * Establish connection between a process and a message queue `name`.
     *
     * Note:
     * Linux prototypes are:
     * mqd_t mq_open (const(char)* name, int oflag);
     * mqd_t mq_open (const(char)* name, int oflag, mode_t mode, mq_attr* attr);
     *
     * Params:
     *   name   = Name of the message queue to open.
     *   oflag  = determines the type of access used.
     *            If `O_CREAT` is on `oflag`, the third argument is taken as a
     *            `mode_t`, the mode of the created message queue.
     *            If `O_CREAT` is on `oflag`, the fourth argument is taken as
     *            a pointer to a `mq_attr' (message queue attributes).
     *            If the fourth argument is `null`, default attributes are used.
     *   ...    = varargs matching the function prototypes
     *
     * Returns:
     *  Message queue descriptor or (mqd_t) -1 on error.
     */
    mqd_t mq_open(const(char)* name, int oflag, ...);


    /**
     * Closes the message queue descriptor mqdes.
     *
     * Params:
     *   mqdes = Message queue descriptor to close.
     *
     * Returns:
     *   On success mq_close() returns 0; on error, -1 is returned, with errno
     *   set to indicate the error.
     */
    int mq_close (mqd_t mqdes);


    /**
     * Query status and attributes of message queue `mqdes`.
     *
     * Params:
     *   mqdes  = Message queue descriptor.
     *   mqstat = Buffer to fill with the message queue's attributes.
     *
     * Returns:
     *   On success mq_getattr() return 0; on error, -1 is returned, with errno
     *   set to indicate the error.
     */
    int mq_getattr (mqd_t mqdes, mq_attr* mqstat);


    /*
     * Set attributes associated with message queue `mqdes`
     *
     * Params:
     *   mqdes   = Message queue descriptor.
     *   newstat = non-null pointer to fill with attributes for `mqdes`.
     *   oldstat = if not `null` it is filled with the old attributes.
     *
     * Returns:
     *   On success mq_setattr() return 0; on error, -1 is returned, with errno
     *   set to indicate the error.
     */
    int mq_setattr (mqd_t mqdes, const(mq_attr)* newstat, mq_attr* oldstat);


    /**
     * Remove the specified message queue `name`.
     *
     * Params:
     *   name = Name of the queue to remove.
     *
     * Returns:
     *   On success mq_unlink() returns 0; on error, -1 is returned, with errno
     *   set to indicate the error.
     */
    int mq_unlink (const(char)* name);


    /**
     * Register for notification when a message is available
     *
     * Params:
     *   mqdes        = Message queue descriptor.
     *   notification = See `man 3 mq_notify` for details.
     *
     * Returns:
     *   On success mq_notify() returns 0; on error, -1 is returned, with errno
     *   set to indicate the error.
     */
    int mq_notify (mqd_t mqdes, const(sigevent)* notification);


    /**
     * Receive the oldest message with the highest priority the message queue
     *
     * Params:
     *   mqdes      = Message queue descriptor.
     *   msg_ptr    = Buffer to write the message to
     *   msg_len    = Size of the buffer provided as `msg_ptr`. Must be greater
     *                than the mq_msgsize attribute of the queue.
     *   msg_prio   = If not `null`, set to the priority of this message.
     *
     * Returns:
     *   On success, mq_receive() returns the number of bytes in the received
     *   message; on error, -1 is returned, with errno set to indicate the error
     */
    ssize_t mq_receive (mqd_t mqdes, char* msg_ptr, size_t msg_len, uint* msg_prio);


    /**
     * Receive the oldest message with the highest priority the message queue,
     * wait up to a certain timeout.
     *
     * Params:
     *   mqdes       = Message queue descriptor.
     *   msg_ptr     = Buffer to write the message to
     *   msg_len     = Size of the buffer provided as `msg_ptr`. Must be greater
     *                 than the mq_msgsize attribute of the queue.
     *   msg_prio    = If not `null`, set to the priority of this message.
     *   abs_timeout = Specify a ceiling on the time to block if the queue is empty.
     *
     * Returns:
     *   On success, mq_receive() returns the number of bytes in the received
     *   message; on error, -1 is returned, with errno set to indicate the error
     */
    pragma(mangle, muslRedirTime64Mangle!("mq_timedreceive", "__mq_timedreceive_time64"))
    ssize_t mq_timedreceive (mqd_t mqdes, char* msg_ptr, size_t msg_len,
                             uint* msg_prio, const(timespec)* abs_timeout);


    /**
     * Add a message to a message queue.
     *
     * Params:
     *   mqdes      = Message queue descriptor.
     *   msg_ptr    = Buffer to read the message from
     *   msg_len    = Size of the message provided via `msg_ptr`. Must be lower
     *                or equal to the mq_msgsize attribute of the queue.
     *   msg_prio   = Priority of this message.
     *
     * Returns:
     *   On success, mq_send() return zero; on error, -1 is returned, with errno
     *   set to indicate the error.
     */
    int mq_send (mqd_t mqdes, const(char)* msg_ptr, size_t msg_len, uint msg_prio);


    /**
     * Add a message to a message queue, block up to a certain time if the queue
     * is full.
     *
     * Params:
     *   mqdes      = Message queue descriptor.
     *   msg_ptr    = Buffer to read the message from
     *   msg_len    = Size of the message provided via `msg_ptr`. Must be lower
     *                or equal to the mq_msgsize attribute of the queue.
     *   msg_prio   = Priority of this message.
     *   abs_timeout = Specify a ceiling on the time to block if the queue is empty.
     *
     * Returns:
     *   On success, mq_timedsend() return zero; on error, -1 is returned,
     *   with errno set to indicate the error.
     *
     */
    pragma(mangle, muslRedirTime64Mangle!("mq_timedsend", "__mq_timedsend_time64"))
    int mq_timedsend (mqd_t mqdes, const(char)* msg_ptr, size_t msg_len,
                       uint msg_prio, const(timespec)* abs_timeout);
}
else version (FreeBSD)
{
    private struct __mq;

    alias mqd_t = __mq*;

    struct mq_attr
    {
        c_long    mq_flags;
        c_long    mq_maxmsg;
        c_long    mq_msgsize;
        c_long    mq_curmsgs;
        c_long[4] __reserved;
    }

    int mq_close(mqd_t);

    int mq_getattr(mqd_t, mq_attr*);

    int mq_notify(mqd_t, const sigevent*);

    mqd_t mq_open(const char*, int, ...);

    ssize_t mq_receive(mqd_t, char*, size_t, uint*);

    int mq_send(mqd_t, const char*, size_t, uint);

    int mq_setattr(mqd_t, const mq_attr*, mq_attr*);

    ssize_t mq_timedreceive(mqd_t, char*, size_t, uint*, const timespec*);

    int mq_timedsend(mqd_t, const char*, size_t, uint, const timespec*);

    int mq_unlink(const char*);
}