[apple/xnu.git] / osfmk / ipc / ipc_mqueue.h

/*
 * Copyright (c) 2000-2004 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_OSREFERENCE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code 
 * as defined in and that are subject to the Apple Public Source License 
 * Version 2.0 (the 'License'). You may not use this file except in 
 * compliance with the License.  The rights granted to you under the 
 * License may not be used to create, or enable the creation or 
 * redistribution of, unlawful or unlicensed copies of an Apple operating 
 * system, or to circumvent, violate, or enable the circumvention or 
 * violation of, any terms of an Apple operating system software license 
 * agreement.
 *
 * Please obtain a copy of the License at 
 * http://www.opensource.apple.com/apsl/ and read it before using this 
 * file.
 *
 * The Original Code and all software distributed under the License are 
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 
 * Please see the License for the specific language governing rights and 
 * limitations under the License.
 *
 * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
 */
/*
 * @OSF_COPYRIGHT@
 */
/* 
 * Mach Operating System
 * Copyright (c) 1991,1990,1989 Carnegie Mellon University
 * All Rights Reserved.
 * 
 * Permission to use, copy, modify and distribute this software and its
 * documentation is hereby granted, provided that both the copyright
 * notice and this permission notice appear in all copies of the
 * software, derivative works or modified versions, and any portions
 * thereof, and that both notices appear in supporting documentation.
 * 
 * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
 * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
 * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
 * 
 * Carnegie Mellon requests users of this software to return to
 * 
 *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
 *  School of Computer Science
 *  Carnegie Mellon University
 *  Pittsburgh PA 15213-3890
 * 
 * any improvements or extensions that they make and grant Carnegie Mellon
 * the rights to redistribute these changes.
 */
/*
 */
/*
 *	File:	ipc/ipc_mqueue.h
 *	Author:	Rich Draves
 *	Date:	1989
 *
 *	Definitions for message queues.
 */

#ifndef	_IPC_IPC_MQUEUE_H_
#define _IPC_IPC_MQUEUE_H_

#include <mach_assert.h>

#include <mach/message.h>

#include <kern/assert.h>
#include <kern/macro_help.h>
#include <kern/kern_types.h>
#include <kern/wait_queue.h>

#include <ipc/ipc_kmsg.h>
#include <ipc/ipc_object.h>
#include <ipc/ipc_types.h>

typedef struct ipc_mqueue {
	union {
		struct {
			struct  wait_queue	wait_queue;	
			struct ipc_kmsg_queue	messages;
			mach_port_msgcount_t	msgcount;
			mach_port_msgcount_t	qlimit;
		 	mach_port_seqno_t 	seqno;
			boolean_t		fullwaiters;
		} port;
		struct wait_queue_set		set_queue;
	} data;
} *ipc_mqueue_t;

#define	IMQ_NULL		((ipc_mqueue_t) 0)

#define imq_wait_queue		data.port.wait_queue
#define imq_messages		data.port.messages
#define imq_msgcount		data.port.msgcount
#define imq_qlimit		data.port.qlimit
#define imq_seqno		data.port.seqno
#define imq_fullwaiters		data.port.fullwaiters

#define imq_set_queue		data.set_queue
#define imq_setlinks		data.set_queue.wqs_setlinks
#define imq_is_set(mq)		wait_queue_is_set(&(mq)->imq_set_queue)

#define	imq_lock(mq)		wait_queue_lock(&(mq)->imq_wait_queue)
#define	imq_lock_try(mq)	wait_queue_lock_try(&(mq)->imq_wait_queue)
#define	imq_unlock(mq)		wait_queue_unlock(&(mq)->imq_wait_queue)
#define imq_held(mq)		wait_queue_held(&(mq)->imq_wait_queue)

#define imq_full(mq)		((mq)->imq_msgcount >= (mq)->imq_qlimit)

extern int ipc_mqueue_full;
extern int ipc_mqueue_rcv;

#define IPC_MQUEUE_FULL		(event64_t)&ipc_mqueue_full
#define IPC_MQUEUE_RECEIVE	(event64_t)&ipc_mqueue_rcv

/*
 * Exported interfaces
 */

/* Initialize a newly-allocated message queue */
extern void ipc_mqueue_init(
	ipc_mqueue_t		mqueue,
	boolean_t		is_set);

/* destroy an mqueue */
extern void ipc_mqueue_destroy(
	ipc_mqueue_t		mqueue);

/* Wake up receivers waiting in a message queue */
extern void ipc_mqueue_changed(
	ipc_mqueue_t		mqueue);

/* Add the specific mqueue as a member of the set */
extern kern_return_t ipc_mqueue_add(
	ipc_mqueue_t		mqueue,
	ipc_mqueue_t	 	set_mqueue);

/* Check to see if mqueue is member of set_mqueue */
extern boolean_t ipc_mqueue_member(
	ipc_mqueue_t		mqueue,
	ipc_mqueue_t		set_mqueue);

/* Remove an mqueue from a specific set */
extern kern_return_t ipc_mqueue_remove(
	ipc_mqueue_t	 	mqueue,
	ipc_mqueue_t		set_mqueue);

/* Remove an mqueue from all sets */
extern void ipc_mqueue_remove_from_all(
	ipc_mqueue_t		mqueue);

/* Remove all the members of the specifiied set */
extern void ipc_mqueue_remove_all(
	ipc_mqueue_t		mqueue);

/* Send a message to a port */
extern mach_msg_return_t ipc_mqueue_send(
	ipc_mqueue_t		mqueue,
	ipc_kmsg_t		kmsg,
	mach_msg_option_t	option,
	mach_msg_timeout_t	timeout_val);

/* Deliver message to message queue or waiting receiver */
extern void ipc_mqueue_post(
	ipc_mqueue_t		mqueue,
	ipc_kmsg_t		kmsg);

/* Receive a message from a message queue */
extern void ipc_mqueue_receive(
	ipc_mqueue_t		mqueue,
	mach_msg_option_t	option,
	mach_msg_size_t		max_size,
	mach_msg_timeout_t	timeout_val,
	int                     interruptible);

/* Continuation routine for message receive */
extern void ipc_mqueue_receive_continue(
	void			*param,
	wait_result_t		wresult);

/* Select a message from a queue and try to post it to ourself */
extern void ipc_mqueue_select(
	ipc_mqueue_t		mqueue,
	mach_msg_option_t	option,
	mach_msg_size_t		max_size);

/* Clear a message count reservation */
extern void ipc_mqueue_release_msgcount(
	ipc_mqueue_t		mqueue);

/* Change a queue limit */
extern void ipc_mqueue_set_qlimit(
	ipc_mqueue_t		mqueue,
	mach_port_msgcount_t	qlimit);

/* Change a queue's sequence number */
extern void ipc_mqueue_set_seqno(
	ipc_mqueue_t		mqueue, 
	mach_port_seqno_t 	seqno);

/* Convert a name in a space to a message queue */
extern mach_msg_return_t ipc_mqueue_copyin(
	ipc_space_t		space,
	mach_port_name_t	name,
	ipc_mqueue_t		*mqueuep,
	ipc_object_t		*objectp);

#endif	/* _IPC_IPC_MQUEUE_H_ */
Commit	Line	Data
1c79356b	1	/*
91447636	2	* Copyright (c) 2000-2004 Apple Computer, Inc. All rights reserved.
1c79356b	3	*
8ad349bb	4	* @APPLE_LICENSE_OSREFERENCE_HEADER_START@
1c79356b	5	*
8ad349bb A	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. The rights granted to you under the
	10	* License may not be used to create, or enable the creation or
	11	* redistribution of, unlawful or unlicensed copies of an Apple operating
	12	* system, or to circumvent, violate, or enable the circumvention or
	13	* violation of, any terms of an Apple operating system software license
	14	* agreement.
	15	*
	16	* Please obtain a copy of the License at
	17	* http://www.opensource.apple.com/apsl/ and read it before using this
	18	* file.
	19	*
	20	* The Original Code and all software distributed under the License are
	21	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	22	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	23	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	24	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	25	* Please see the License for the specific language governing rights and
	26	* limitations under the License.
	27	*
	28	* @APPLE_LICENSE_OSREFERENCE_HEADER_END@
1c79356b A	29	*/
	30	/*
	31	* @OSF_COPYRIGHT@
	32	*/
	33	/*
	34	* Mach Operating System
	35	* Copyright (c) 1991,1990,1989 Carnegie Mellon University
	36	* All Rights Reserved.
	37	*
	38	* Permission to use, copy, modify and distribute this software and its
	39	* documentation is hereby granted, provided that both the copyright
	40	* notice and this permission notice appear in all copies of the
	41	* software, derivative works or modified versions, and any portions
	42	* thereof, and that both notices appear in supporting documentation.
	43	*
	44	* CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
	45	* CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
	46	* ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
	47	*
	48	* Carnegie Mellon requests users of this software to return to
	49	*
	50	* Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
	51	* School of Computer Science
	52	* Carnegie Mellon University
	53	* Pittsburgh PA 15213-3890
	54	*
	55	* any improvements or extensions that they make and grant Carnegie Mellon
	56	* the rights to redistribute these changes.
	57	*/
	58	/*
	59	*/
	60	/*
	61	* File: ipc/ipc_mqueue.h
	62	* Author: Rich Draves
	63	* Date: 1989
	64	*
	65	* Definitions for message queues.
	66	*/
	67
	68	#ifndef _IPC_IPC_MQUEUE_H_
	69	#define _IPC_IPC_MQUEUE_H_
	70
	71	#include <mach_assert.h>
	72
	73	#include <mach/message.h>
	74
	75	#include <kern/assert.h>
	76	#include <kern/macro_help.h>
91447636	77	#include <kern/kern_types.h>
1c79356b A	78	#include <kern/wait_queue.h>
	79
	80	#include <ipc/ipc_kmsg.h>
	81	#include <ipc/ipc_object.h>
	82	#include <ipc/ipc_types.h>
	83
	84	typedef struct ipc_mqueue {
	85	union {
	86	struct {
	87	struct wait_queue wait_queue;
	88	struct ipc_kmsg_queue messages;
	89	mach_port_msgcount_t msgcount;
	90	mach_port_msgcount_t qlimit;
	91	mach_port_seqno_t seqno;
	92	boolean_t fullwaiters;
	93	} port;
9bccf70c	94	struct wait_queue_set set_queue;
1c79356b A	95	} data;
	96	} *ipc_mqueue_t;
	97
	98	#define IMQ_NULL ((ipc_mqueue_t) 0)
	99
	100	#define imq_wait_queue data.port.wait_queue
	101	#define imq_messages data.port.messages
	102	#define imq_msgcount data.port.msgcount
	103	#define imq_qlimit data.port.qlimit
	104	#define imq_seqno data.port.seqno
	105	#define imq_fullwaiters data.port.fullwaiters
	106
	107	#define imq_set_queue data.set_queue
9bccf70c A	108	#define imq_setlinks data.set_queue.wqs_setlinks
9bccf70c A	109	#define imq_is_set(mq) wait_queue_is_set(&(mq)->imq_set_queue)
1c79356b A	110
	111	#define imq_lock(mq) wait_queue_lock(&(mq)->imq_wait_queue)
	112	#define imq_lock_try(mq) wait_queue_lock_try(&(mq)->imq_wait_queue)
	113	#define imq_unlock(mq) wait_queue_unlock(&(mq)->imq_wait_queue)
	114	#define imq_held(mq) wait_queue_held(&(mq)->imq_wait_queue)
	115
	116	#define imq_full(mq) ((mq)->imq_msgcount >= (mq)->imq_qlimit)
	117
	118	extern int ipc_mqueue_full;
	119	extern int ipc_mqueue_rcv;
	120
9bccf70c A	121	#define IPC_MQUEUE_FULL (event64_t)&ipc_mqueue_full
9bccf70c A	122	#define IPC_MQUEUE_RECEIVE (event64_t)&ipc_mqueue_rcv
1c79356b A	123
	124	/*
	125	* Exported interfaces
	126	*/
	127
	128	/* Initialize a newly-allocated message queue */
	129	extern void ipc_mqueue_init(
91447636 A	130	ipc_mqueue_t mqueue,
	131	boolean_t is_set);
	132
	133	/* destroy an mqueue */
	134	extern void ipc_mqueue_destroy(
	135	ipc_mqueue_t mqueue);
1c79356b	136
1c79356b A	137	/* Wake up receivers waiting in a message queue */
	138	extern void ipc_mqueue_changed(
	139	ipc_mqueue_t mqueue);
	140
91447636 A	141	/* Add the specific mqueue as a member of the set */
	142	extern kern_return_t ipc_mqueue_add(
	143	ipc_mqueue_t mqueue,
	144	ipc_mqueue_t set_mqueue);
	145
	146	/* Check to see if mqueue is member of set_mqueue */
	147	extern boolean_t ipc_mqueue_member(
	148	ipc_mqueue_t mqueue,
	149	ipc_mqueue_t set_mqueue);
	150
	151	/* Remove an mqueue from a specific set */
	152	extern kern_return_t ipc_mqueue_remove(
	153	ipc_mqueue_t mqueue,
	154	ipc_mqueue_t set_mqueue);
	155
	156	/* Remove an mqueue from all sets */
	157	extern void ipc_mqueue_remove_from_all(
	158	ipc_mqueue_t mqueue);
	159
	160	/* Remove all the members of the specifiied set */
	161	extern void ipc_mqueue_remove_all(
	162	ipc_mqueue_t mqueue);
	163
1c79356b A	164	/* Send a message to a port */
	165	extern mach_msg_return_t ipc_mqueue_send(
	166	ipc_mqueue_t mqueue,
	167	ipc_kmsg_t kmsg,
	168	mach_msg_option_t option,
91447636	169	mach_msg_timeout_t timeout_val);
1c79356b A	170
	171	/* Deliver message to message queue or waiting receiver */
	172	extern void ipc_mqueue_post(
	173	ipc_mqueue_t mqueue,
	174	ipc_kmsg_t kmsg);
	175
	176	/* Receive a message from a message queue */
	177	extern void ipc_mqueue_receive(
	178	ipc_mqueue_t mqueue,
	179	mach_msg_option_t option,
	180	mach_msg_size_t max_size,
91447636	181	mach_msg_timeout_t timeout_val,
1c79356b A	182	int interruptible);
	183
	184	/* Continuation routine for message receive */
91447636 A	185	extern void ipc_mqueue_receive_continue(
	186	void *param,
	187	wait_result_t wresult);
1c79356b A	188
	189	/* Select a message from a queue and try to post it to ourself */
	190	extern void ipc_mqueue_select(
	191	ipc_mqueue_t mqueue,
	192	mach_msg_option_t option,
	193	mach_msg_size_t max_size);
	194
	195	/* Clear a message count reservation */
	196	extern void ipc_mqueue_release_msgcount(
	197	ipc_mqueue_t mqueue);
	198
	199	/* Change a queue limit */
	200	extern void ipc_mqueue_set_qlimit(
	201	ipc_mqueue_t mqueue,
	202	mach_port_msgcount_t qlimit);
	203
	204	/* Change a queue's sequence number */
	205	extern void ipc_mqueue_set_seqno(
	206	ipc_mqueue_t mqueue,
	207	mach_port_seqno_t seqno);
	208
	209	/* Convert a name in a space to a message queue */
	210	extern mach_msg_return_t ipc_mqueue_copyin(
	211	ipc_space_t space,
	212	mach_port_name_t name,
	213	ipc_mqueue_t *mqueuep,
	214	ipc_object_t *objectp);
	215
	216	#endif /* _IPC_IPC_MQUEUE_H_ */