Kbase 17143: WIN32 API - What exactly is an Atom?
| Autor |
Progress Software Corporation - Progress |
| Acesso |
Público |
| Publicação |
10/05/1998 |
|
WIN32 API - What exactly is an Atom?
INTRODUCTION:
=============
This knowledgebase entry describes exactly what an "Atom" is in the
MS-Windows world and what you could possibly use it for.
The following information is quoted directly from the book titled:
- Windows 95 WIN32 Programming API Bible from The Waite Group
The Win32 API allows applications to store strings in structures known
as atom tables. Once a program stores a string in an atom table, the
program may reference the string using an atom. An atom is a unique
16-bit value that is associated with a constant string value. Using
an atom as a reference to a string is similar to using a memory handle
to reference a block of shared global data. Just as an application
can pass a memory handle to the Win32 API to obtain a pointer to the
contents of a block of data (by using GlobalLock()), an application
may call the Win32 API to obtain the value of a string associated with
an atom. This string value that an atom represents is known as its
atom name.
Atoms may be used by applications to save memory. Storing strings
that occur more than once in an application's atom table conserves
memory because the string value is stored only once. Other occurences
of the string only occupy the two bytes of memory required for the
atom, rather than the number of bytes necessary to store a copy of the
actual string. Another reason to store strings as atoms is that atom
tables speed performance when comparing strings because, instead of
comparing each bytes of two strings, only the 16-bit atoms of the
strings are compared.
Atoms are also important in data exchange between programs. An atom
table global to all applications, the "global atom table", is used to
exchange data between applications. The use of atoms to exchange
strings between applications is one of the foundations of Dynamic Data
Exchange (DDE). Atoms are also commonly used to store variable length
strings in Object Link Embedding (OLE) object descriptors. The use of
atoms in OLE data descriptors results in smaller, more easily
exchanged, fixed-size structures.
There are two types of atom tables: local atom tables and the global
atom table. Each process has its own local atom table. The value of
a local atom is unique to the process in which it is defined. Atoms
stored in the global atom table, on the other hand, may be accessed
by any application. For any given global atom, the Win32 API will
return the same atom name to every application.
The AddAtom() function stores strings in a local atom table. Atom
names are stored in exactly the same case they are added. Each time
AddAtom() is called for an already existing atom, Windows increments
an internal reference count for the atom. DeleteAtom() is used to
decrement this reference count. When the reference count reaches
zero, the atom is removed from the atom table.
FindAtom() searches the application's local atom table for an atom
that matches a given string. The search performed is case
insensitive. To return an atom name from the atom table use
GetAtomName(). The atom name is returned in the same case it was
first stored.
A parallel set of atom functions allows global atom tables to be
managed. GlobalAddAtom(), for example, adds atoms to a global atom
table, just as AddAtom() adds atoms to a local atom table. The other
global atom table functions are GlobalDeleteAtom(), GlobalFindAtom(),
and GlobalGetAtomName().
The last atom function, InitAtomTable(), sets the number of top-level
entries in the local atom table to a given value. By default, the
number of top-level entries in both the local atom table and global
atom table is 37. This does not mean that only 37 atoms may be placed
in the table, but rather that the chance of collision (and therefore
slower searches) is more likely with 37 entries in the table than
with, for example, 73. InitAtomTable() must be called before adding
atoms to a local atom table. Also, the value passed should always be
a prime number. If a prime number is not used, there will likely be
more collisions and, therefore, slower searches. There is no
corresponding function for setting the global atom table's number of
top-level entries.
While global atoms are used extensively in the DDE protocol, they also
may be used to exchange string data less formally between instances
of your own application. The sender adds a string to the global atom
table (using GlobalAddAtom()) and then sets a message parameter to
the value of the atom. The receiver uses GlobalFindAtom() to get the
contents of the passed data and deletes the atom using
GlobalDeleteAtom(). It is important to delete the atom or the global
atom table will become cluttered with unneeded entries.
Windows 95 and Windows NT also provide a means of storing strings of
decimal numbers into atom tables. These atoms that represent numeric
strings are called integer atoms. Only values in the range of
1-49151 are permitted. An integer's value may be tested against the
constant MAXINTATOM (has a value of 49151) to determine whether it
can be placed in the atom table. Integer atoms are passed to the
atom management functions as a string in the format "#<number>".
Progress Software Technical Support Note # 17143