prevent multiple namespace pollution by C API
---------------------------------------------
Key: ZOOKEEPER-295
URL: https://issues.apache.org/jira/browse/ZOOKEEPER-295
Project: Zookeeper
Issue Type: Improvement
Components: c client
Affects Versions: 3.0.1, 3.0.0, 3.1.0
Reporter: Chris Darroch
The ZOOKEEPER-6 issue touched on the problem of namespace pollution by the
ZooKeeper C API; this report was closed but I don't think the problem has
actually been substantially resolved.
There are multiple namespaces to consider. First, the names of the C include
files should ideally have a common prefix, e.g., zoo_recordio.h, or else be
concatenated into a single zookeeper.h file. The zookeeper.jute.h include file
has a reasonably good name in this regard.
Second, all macros should ideally have a common prefix, e.g., ZOO_ or ZK_ or
ZOOKEEPER_. Currently many exported constants (not macros) have the ZOO_
prefix, such as ZOO_PERM_READ, but error codes have a Z prefix, e.g., ZOK,
ZNOTEMPTY.
Third, all functions should ideally have a common prefix, e.g., zoo_ or zk_ or
zookeeper_. Many do already, but there is some variation, such as
zookeeper_init(), zookeeper_process(), and there are also a large number of
functions which have no prefix. These include many of the functions defined in
recordio.h and zookeeper.jute.h, such as get_buffer() and serialize_Id(). Many
others are simply used internally within the ZooKeeper C library and not
declared in an external include file, but still pollute the caller's namespace,
e.g., get_xid(), process_completions(), adaptor_init(), etc. All external
symbols in the libraries should have a common prefix.
Fourth, all structure and type definitions should also have a common prefix,
again, zoo_ or zk_ or zookeeper_. This is especially true of structures which
currently have very generic names such as Id, Stat, and ACL from
zookeeper.jute.h; buffer, iarchive, and oarchive from recordio.h; and
clientid_t and watcher_fn from zookeeper.h. The zhandle_t structure should
also be renamed to have the same prefix, e.g., zoo_handle_t.
The ZOOKEEPER-6 report includes the comment that the names in zookeeper.jute.h
will be difficult to change because they affect the Java code and that there
should be "limited exposure since jute naming starts with caps". It would be
nice to think so, but I fear that a structure named Id or Stat is going to be
pretty darn commonplace in other people's code. I would strongly recommend
revising the entire set file, function, macro, type and structure names for
4.0.0.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
