hadoop-zookeeper-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Chris Darroch (JIRA)" <j...@apache.org>
Subject [jira] Created: (ZOOKEEPER-295) prevent multiple namespace pollution by C API
Date Thu, 05 Feb 2009 19:45:59 GMT
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.


Mime
View raw message