Import Be Inc. string atomizer kernel module.

git-svn-id: file:///srv/svn/repos/haiku/trunk/current@4809 a95241bf-73f2-0310-859d-f6bbb57e9c96

headers/os/drivers/atomizer.h

@@ -0,0 +1,97 @@
+/*******************************************************************************
+/
+/	File:			atomizer.h
+/
+/	Description:	Kernel atomizer module API
+/
+/	Copyright 1999, Be Incorporated, All Rights Reserved.
+/
+*******************************************************************************/
+
+#ifndef _ATOMIZER_MODULE_H_
+#define _ATOMIZER_MODULE_H_
+
+#include <module.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+	An atomizer is a software device that returns a unique token for a
+	null-terminated UTF8 string.
+
+	Each atomizer comprises a separate token space.  The same string interned
+	in two different atomizers will generate two distinct tokens.
+
+	Atomizers and the tokens they generate are only guaranteed valid between
+	matched calls to get_module/put_module.
+	
+	void * find_or_make_atomizer(const char *string)
+		Returns a token that identifies the named atomizer, creating a new
+		atomizer if the named atomizer does not exist.  Pass null, a zero
+		length string, or the value B_SYSTEM_ATOMIZER_NAME for string will
+		return a pointer to the system atomizer.  Returns (void *)(0)
+		if the atomizer could not be created (for whatever reason).  A return
+		value of (void *)(-1) refers to the system atomizer.
+
+	status_t delete_atomizer(void *atomizer)
+		Delete the atomizer specified.  Returns B_OK if successfull, B_ERROR
+		otherwise.  An error return usually means that a race condition was
+		detected while destroying the atomizer.
+
+	void * atomize(void *atomizer, const char *string, int create)
+		Return the unique token for the specified string, creating a new token
+		if the string was not previously atomized and create is non-zero.  If
+		atomizer is (void *)(-1), use the system atomizer (saving the step of
+		looking it up with find_or_make_atomizer().  Returns (const char *)(0)
+		if there were any errors detected: insufficient memory or a race
+		condition with someone deleting the atomizer.
+
+	const char * string_for_token(void *atomizer, void *atom)
+		Return a pointer to the string described by atom in the provided atomizer.
+		Returns (const char *)(0) if either the atomizer or the atom were invalid.
+
+	status_t get_next_atomizer_info(void **cookie, atomizer_info *info)
+		Returns info about the next atomizer in the list of atomizers by modifying
+		the contents of info.  The pointer specified by *cookie should be set to
+		(void *)(0) to retrieve the first atomizer, and should not be modified
+		thereafter.  Returns B_ERROR when there are no more atomizers.
+		Adding or deleting atomizers between calls to get_next_atomizer() results
+		in a safe but undefined behavior.
+
+	void * get_next_atom(void *atomizer, uint32 *cookie)
+		Returns the next atom interned in specified atomizer,  *cookie
+		should be set to (uint32)(0) to get the first atom.  Returns
+		(void *)(0) when there are no more atoms.  Adding atoms between
+		calls to get_next_atom() may cause atoms to be skipped.
+
+	Atomizers are SMP-safe.  Check return codes for errors!
+
+*/
+
+#define B_ATOMIZER_MODULE_NAME "generic/atomizer/v1"
+#define B_SYSTEM_ATOMIZER_NAME "BeOS System Atomizer"
+
+typedef struct {
+	void	*atomizer;	/* An opaque token representing the atomizer. */
+	char	name[B_OS_NAME_LENGTH];	/* The first B_OS_NAME_LENGTH bytes of the atomizer name, null terminated. */
+	uint32	atom_count;	/* The number of atoms currently interned in this atomizer. */
+} atomizer_info;
+
+typedef struct {
+	module_info		minfo;
+	const void *	(*find_or_make_atomizer)(const char *string);
+	status_t		(*delete_atomizer)(const void *atomizer);
+	const void *	(*atomize)(const void *atomizer, const char *string, int create);
+	const char *	(*string_for_token)(const void * atomizer, const void *atom);
+	status_t		(*get_next_atomizer_info)(void **cookie, atomizer_info *info);
+	const void *	(*get_next_atom)(const void *atomizer, uint32 *cookie);
+} atomizer_module_info;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
+