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.

Reply via email to