atomizer.h

Go to the documentation of this file.

/*******************************************************************************
/
/   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

---

Copyright 2005 by yellowTAB GmbH, Be Inc., Palm Source Inc. and their respective legal successors
All rights reserved.