| Did you know ... | Search Documentation: |
| Atoms and functors |
The following functions provide for communication using atoms and functors.
(atom_t)0.
The following atoms are provided as macros, giving access to the
empty list symbol and the name of the list constructor. Prior to versionĀ 7,
ATOM_nil is the same as PL_new_atom("[]")
and
ATOM_dot is the same as PL_new_atom(".").
This is no longer the case in SWI-Prolog versionĀ 7.
PL_new_functor(ATOM_dot,2).
It is advised to use
PL_get_list(), PL_put_list()
or PL_unify_list()
where applicable.REP_ISO_LATIN_1, REP_UTF8 or REP_MB.
If
len is (size_t)-1, it is computed from s
using
strlen(). Raises an exception if s violates rep
and returns (atom_t)0. For other error conditions, see PL_new_atom().REP_UTF8, REP_MB
or REP_ISO_LATIN_1. Storage is defined by the BUF_*
flags as described with PL_get_chars().
The flag CVT_EXCEPTION defines whether or not the function
fails silently or raises a Prolog exception. This function may fail
because atom is not a text atom but a blob (see section
12.4.10), conversion to the requested encoding is not possible or a
resource error occurs.term_t
handle should use PL_atom_nchars(), PL_atom_wchars(),
or PL_atom_mbchars().
If it is
known that atom is a classical Prolog text atom, one
can use PL_atom_nchars()
to obtain the C string and its length (for ISO-Latin-1 atoms) or PL_atom_wchars()
to obtain a C wide string (wchar_t).atom_t
is valid.(atom_t)0.
With the introduction of atom garbage collection in version 3.3.0, atoms no longer live as long as the process. Instead, their lifetime is guaranteed only as long as they are referenced. In the single-threaded version, atom garbage collections are only invoked at the call-port. In the multithreaded version (see chapter 10), they appear asynchronously, except for the invoking thread.
For dealing with atom garbage collection, two additional functions are provided:
Please note that the following two calls are different with respect to atom garbage collection:
PL_unify_atom_chars(t, "text");
PL_unify_atom(t, PL_new_atom("text"));
The latter increments the reference count of the atom text,
which effectively ensures the atom will never be collected. It is
advised to use the *_chars() or *_nchars() functions
whenever applicable.
Passing atoms to other threads An atom obtained from a term,
e.g., using PL_get_atom(),
may be a
local atom of the calling thread. This is the case for a new
atom created by PL_unify_chars()
and friends, by read_term/2
or
PL_chars_to_term(),
and for blobs of a type with PL_BLOB_LOCAL (see section
12.4.10.1). Such an atom is reclaimed by the owning thread as soon
as its own stacks no longer reference it, regardless of whether another
thread uses the handle. Foreign code that hands an atom_t
to another thread, e.g., by storing it in a C variable, a queue or a
data structure that is shared between threads, must call PL_register_atom()
before doing so. PL_register_atom()
turns the atom into an ordinary atom, which the atom garbage collector
protects as long as any thread references it. The other thread may
therefore call
PL_unregister_atom()
as soon as the atom is reachable from one of its own term references,
e.g., after PL_put_atom().
Strictly, this was always required, but before local atoms existed the
omission was usually harmless because the global atom garbage collector
scans the stacks of all threads. Without the registration, the other
thread may use an atom that has been reclaimed, which leads to wrong
results or a crash. Debug builds of SWI-Prolog report the use of another
thread's local atom through the foreign language interface as an API
error.