The following functions provide for communication using atoms and
functors.
- atom_t PL_new_atom(const
char *)
- Return an atom handle for the given C-string. This function always
succeeds. The returned handle is valid as long as the atom is referenced
(see section
12.4.2.1). 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 long the case in SWI-Prolog version 7.
- atom_t ATOM_nil(ATOM_nil)
- tomic constant that represents the empty list. It is adviced to use PL_get_nil(), PL_put_nil()
or PL_unify_nil()
where applicable.
- atom_t ATOM_dot(ATOM_dot)
- tomic constant that represents the name of the list constructor. The
list constructor itself is created using
PL_new_functor(ATOM_dot,2).
It is adviced to use
PL_get_list(), PL_put_list()
or PL_unify_list()
where applicable.
- atom_t PL_new_atom_mbchars(int
rep, size_t len, const char *s)
- This function generalizes PL_new_atom()
and PL_new_atom_nchars()
while allowing for multiple encodings. The rep argument is
one of
REP_ISO_LATIN_1, REP_UTF8 or REP_MB.
If
len is (size_t)-1, it is computed from s
using strlen().
- const char* PL_atom_chars(atom_t
atom)
- Return a C-string for the text represented by the given atom. The
returned text will not be changed by Prolog. It is not allowed to modify
the contents, not even `temporary' as the string may reside in read-only
memory. The returned string becomes invalid if the atom is garbage
collected (see section
12.4.2.1). Foreign functions that require the text from an atom
passed in a
term_t normally use
PL_get_atom_chars()
or PL_get_atom_nchars().
- functor_t PL_new_functor(atom_t
name, int arity)
- Returns a functor identifier, a handle for the name/arity pair.
The returned handle is valid for the entire Prolog session.
- atom_t PL_functor_name(functor_t
f)
- Return an atom representing the name of the given functor.
- size_t PL_functor_arity(functor_t
f)
- Return the arity of the given functor.
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:
- void PL_register_atom(atom_t
atom)
- Increment the reference count of the atom by one. PL_new_atom()
performs this automatically, returning an atom with a reference count of
at least one.178Otherwise
asynchronous atom garbage collection might destroy the atom before it is
used.
- void PL_unregister_atom(atom_t
atom)
- Decrement the reference count of the atom. If the reference count drops
below zero, an assertion error is raised.
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.