/*********************************************************************************************************
* Software License Agreement (BSD License)                                                               *
* Author: Sebastien Decugis <sdecugis@nict.go.jp>							 *
*													 *
* Copyright (c) 2008, WIDE Project and NICT								 *
* All rights reserved.											 *
* 													 *
* Redistribution and use of this software in source and binary forms, with or without modification, are  *
* permitted provided that the following conditions are met:						 *
* 													 *
* * Redistributions of source code must retain the above 						 *
*   copyright notice, this list of conditions and the 							 *
*   following disclaimer.										 *
*    													 *
* * Redistributions in binary form must reproduce the above 						 *
*   copyright notice, this list of conditions and the 							 *
*   following disclaimer in the documentation and/or other						 *
*   materials provided with the distribution.								 *
* 													 *
* * Neither the name of the WIDE Project or NICT nor the 						 *
*   names of its contributors may be used to endorse or 						 *
*   promote products derived from this software without 						 *
*   specific prior written permission of WIDE Project and 						 *
*   NICT.												 *
* 													 *
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED *
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A *
* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR *
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 	 *
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 	 *
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR *
* TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF   *
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.								 *
*********************************************************************************************************/

/* Messages queues module.
 * 
 * This module provides the support functions for queueing and picking messages.
 */

#ifndef _QUEUES_H
#define _QUEUES_H

#include <waaad/message-api.h>
#include <time.h>

/* The following opaque type represents a message queue. -- we don't use mq_ to avoid confusion with POSIX */
typedef void meq_t;

/* The following queues are global objects */
extern meq_t * g_meq_incoming;	/* Received messages */
extern meq_t * g_meq_outgoing;	/* Messages to send */
extern meq_t * g_meq_local;	/* Messages for local handling */


/*
 * FUNCTION:	meq_init
 *
 * PARAMETERS:
 *  -
 *
 * DESCRIPTION: 
 *  Initialize the message queues module and the global queues. 
 *
 * RETURN VALUE:
 *   0	: Application is now ready to use the module.
 *  !0  : An error occurred. 
 */
int meq_init ( void );

/*
 * FUNCTION:	meq_fini
 *
 * PARAMETERS:
 *  -
 *
 * DESCRIPTION: 
 *  Terminates the module. No que_* function must be called after this one.
 *
 * RETURN VALUE:
 *   0 : module closed properly.
 *  !0 : an error occurred (we may ignore it)
 */
int meq_fini ( void );

/*
 * FUNCTION:	meq_new
 *
 * PARAMETERS:
 *  queue	: Upon success, a pointer to the new message queue is saved here.
 *
 * DESCRIPTION: 
 *  Create a new empty message queue.
 *
 * RETURN VALUE :
 *  0		: The message queue has been initialized successfully.
 *  EINVAL 	: The parameter is invalid.
 *  ENOMEM	: Not enough memory to complete the creation.  
 */
int meq_new ( meq_t ** queue );

/*
 * FUNCTION:	meq_del
 *
 * PARAMETERS:
 *  queue	: Pointer to an empty message queue to delete.
 *
 * DESCRIPTION: 
 *  Destroys a message queue. This is only possible if no thread is waiting for a message,
 * and the queue is empty.
 *
 * RETURN VALUE:
 *  0		: The message queue has been destroyed successfully.
 *  EINVAL 	: The parameter is invalid.
 */
int meq_del ( meq_t ** queue );

/*
 * FUNCTION:	meq_length
 *
 * PARAMETERS:
 *  queue	: The queue from which to retrieve the length.
 *  length	: Upon success, the number of messages in the queue is stored here.
 *
 * DESCRIPTION: 
 *  Retrieve the number of messages pending in a queue. This may help to dynamically adjust the number of
 * producer / consumer threads for example.
 *
 * RETURN VALUE:
 *  0		: The length of the queue has been written.
 *  EINVAL 	: A parameter is invalid.
 */
int meq_length ( meq_t * queue, int * length );
int meq_length_noerr ( meq_t * queue );

/*
 * FUNCTION:	meq_post
 *
 * PARAMETERS:
 *  queue	: The queue in which the message must be posted.
 *  msg		: The message that is put in the queue.
 *
 * DESCRIPTION: 
 *  A message is added in a queue. Threads may retrieve the messages from the queue (in FIFO order)
 *  with the meq_get, meq_tryget, or meq_timedget functions.
 *
 * RETURN VALUE:
 *  0		: The message is queued.
 *  EINVAL 	: A parameter is invalid.
 *  ENOMEM 	: Not enough memory to complete the operation.
 */
int meq_post ( meq_t * queue, msg_t * msg );

/*
 * FUNCTION:	meq_get
 *
 * PARAMETERS:
 *  queue	: The queue from which the message must be retrieved.
 *  msg		: On return, the message is stored here.
 *
 * DESCRIPTION: 
 *  This function retrieves a message from a queue. If the queue is empty, the function will block the 
 * thread until a new message is posted to the queue, or until the thread is canceled (in which case the 
 * function does not return).
 *
 * RETURN VALUE:
 *  0		: A new message has been retrieved.
 *  EINVAL 	: A parameter is invalid.
 */
int meq_get ( meq_t * queue, msg_t ** msg );

/*
 * FUNCTION:	meq_tryget
 *
 * PARAMETERS:
 *  queue	: The queue from which the message must be retrieved.
 *  msg		: On return, the message is stored here.
 *
 * DESCRIPTION: 
 *  This function is similar to meq_get, except that it will not block if 
 * the queue is empty, but return EWOULDBLOCK instead.
 *
 * RETURN VALUE:
 *  0		: A new message has been retrieved.
 *  EINVAL 	: A parameter is invalid.
 *  EWOULDBLOCK : The queue was empty.
 */
int meq_tryget ( meq_t * queue, msg_t ** msg );

/*
 * FUNCTION:	meq_timedget
 *
 * PARAMETERS:
 *  queue	: The queue from which the message must be retrieved.
 *  msg		: On return, the message is stored here.
 *  abstime	: the absolute time until which we allow waiting for a message.
 *
 * DESCRIPTION: 
 *  This function is similar to meq_get, except that it will block if the queue is empty 
 * only until the absolute time abstime (see pthread_cond_timedwait for + info).
 * If the queue is still empty when the time expires, 
 *
 * RETURN VALUE:
 *  0		: A new message has been retrieved.
 *  EINVAL 	: A parameter is invalid.
 *  ETIMEDOUT   : The time out has passed and no message has been received.
 */
int meq_timedget ( meq_t * queue, msg_t ** msg, const struct timespec *abstime );


#endif /* _QUEUES_H */