[apple/libc.git] / include / libkern / OSMemoryNotification.h

/*
 * Copyright (c) 2006 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_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. 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_HEADER_END@
 */

#ifndef _OSMEMORYNOTIFICATION_H_
#define _OSMEMORYNOTIFICATION_H_

#include <sys/cdefs.h>

/*
**  OSMemoryNotification.h
**  
**  Kernel-generated notification mechanism to alert registered tasks when physical memory
**  pressure reaches certain thresholds. Notifications are triggered in both directions
**  so clients can manage their memory usage more and less aggressively.
**
*/

__BEGIN_DECLS

struct timeval;

/*
** Opaque type for notification object
*/
 
typedef struct _OSMemoryNotification * OSMemoryNotificationRef;

/*
** Threshold values for notifications
*/
 
typedef enum {
	OSMemoryNotificationLevelAny      = -1,
	OSMemoryNotificationLevelNormal   =  0,
	OSMemoryNotificationLevelWarning  =  1,
	OSMemoryNotificationLevelUrgent   =  2,
	OSMemoryNotificationLevelCritical =  3
} OSMemoryNotificationLevel;

/*
** Creation routines. Returns the created OSMemoryNotificationRef in the note param.
** returns: 0 on success
**          ENOMEM if insufficient memory or resources exists to create the notification object
**          EINVAL if the threshold is not a valid notification level
*/

int OSMemoryNotificationCreate(OSMemoryNotificationRef *note);

/*
** returns: 0 on success
**          EINVAL if the notification is not an initialized notification object
*/

int OSMemoryNotificationDestroy(OSMemoryNotificationRef note);

/*
** Block waiting for notification
** returns: 0 on success, with the level that triggered the notification in the level param
**          EINVAL if the notification object is invalid
**          ETIMEDOUT if abstime passes before notification occurs
*/
int OSMemoryNotificationWait(OSMemoryNotificationRef note, OSMemoryNotificationLevel *level);
int OSMemoryNotificationTimedWait(OSMemoryNotificationRef note, OSMemoryNotificationLevel *level, const struct timeval *abstime);

/*
** Simple polling interface to detect current memory pressure level
*/

OSMemoryNotificationLevel OSMemoryNotificationCurrentLevel(void);

/*
** External notify(3) string for manual notification setup
*/

extern const char *kOSMemoryNotificationName;

__END_DECLS

#endif /* _OSMEMORYNOTIFICATION_H_ */
Commit	Line	Data
b5d655f7 A	1	/*
	2	* Copyright (c) 2006 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
	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. Please obtain a copy of the License at
	10	* http://www.opensource.apple.com/apsl/ and read it before using this
	11	* file.
	12	*
	13	* The Original Code and all software distributed under the License are
	14	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	15	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	16	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	17	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	18	* Please see the License for the specific language governing rights and
	19	* limitations under the License.
	20	*
	21	* @APPLE_LICENSE_HEADER_END@
	22	*/
	23
	24	#ifndef _OSMEMORYNOTIFICATION_H_
	25	#define _OSMEMORYNOTIFICATION_H_
	26
	27	#include <sys/cdefs.h>
	28
	29	/*
	30	** OSMemoryNotification.h
	31	**
	32	** Kernel-generated notification mechanism to alert registered tasks when physical memory
	33	** pressure reaches certain thresholds. Notifications are triggered in both directions
	34	** so clients can manage their memory usage more and less aggressively.
	35	**
	36	*/
	37
	38	__BEGIN_DECLS
	39
	40	struct timeval;
	41
	42	/*
	43	** Opaque type for notification object
	44	*/
	45
	46	typedef struct _OSMemoryNotification * OSMemoryNotificationRef;
	47
	48	/*
	49	** Threshold values for notifications
	50	*/
	51
	52	typedef enum {
	53	OSMemoryNotificationLevelAny = -1,
	54	OSMemoryNotificationLevelNormal = 0,
	55	OSMemoryNotificationLevelWarning = 1,
	56	OSMemoryNotificationLevelUrgent = 2,
	57	OSMemoryNotificationLevelCritical = 3
	58	} OSMemoryNotificationLevel;
	59
	60	/*
	61	** Creation routines. Returns the created OSMemoryNotificationRef in the note param.
	62	** returns: 0 on success
	63	** ENOMEM if insufficient memory or resources exists to create the notification object
	64	** EINVAL if the threshold is not a valid notification level
65	*/
66
67	int OSMemoryNotificationCreate(OSMemoryNotificationRef *note);
68
69	/*
70	** returns: 0 on success
71	** EINVAL if the notification is not an initialized notification object
72	*/
73
74	int OSMemoryNotificationDestroy(OSMemoryNotificationRef note);
75
76	/*
77	** Block waiting for notification
78	** returns: 0 on success, with the level that triggered the notification in the level param
79	** EINVAL if the notification object is invalid
80	** ETIMEDOUT if abstime passes before notification occurs
81	*/
82	int OSMemoryNotificationWait(OSMemoryNotificationRef note, OSMemoryNotificationLevel *level);
83	int OSMemoryNotificationTimedWait(OSMemoryNotificationRef note, OSMemoryNotificationLevel level, const struct timeval abstime);
84
85	/*
86	** Simple polling interface to detect current memory pressure level
87	*/
88
89	OSMemoryNotificationLevel OSMemoryNotificationCurrentLevel(void);
90
91	/*
92	** External notify(3) string for manual notification setup
93	*/
94
95	extern const char *kOSMemoryNotificationName;
96
97	__END_DECLS
98
99	#endif /* _OSMEMORYNOTIFICATION_H_ */