List:Internals« Previous MessageNext Message »
From:Konstantin Osipov Date:June 16 2009 12:11pm
Subject:Re: RFC: draft of physical structure of server code
View as plain text  
Hi Mats,

Thank you very much for defining the basis of the server module
management. 

* Mats Kindahl <mats@stripped> [09/06/12 00:07]:

> In order to accomplish this, we want to have a structure that supports
> hierarchical testing, that is, directly testing individual components of
> the server as well as testing subsystems of the server.

I think this property could be explored/described in a bit higher
detail. Please see below on package dependencies, versions, and
interaction with the plugin registry and plugin architecture.

> Note that this proposal mentions a few coding rules that are needed to
> support the proposed structure, but the goal of this work is *not* to
> produce a set of coding guidelines.  The maintenance of coding
> guidelines is a separate issue and is maintained by the coding
> guidelines committee (which is currently headed by Kostja).

This document does suggest several additions to the coding guidelines,
such as having the header guards, naming convention for
header guards, use of C++ namespaces, naming convention for
namespaces.
These I would love the coding style group to consider. 

Alternatively, if this proposal is just accepted as a whole
package, I will unilaterally extend the coding standard to include
bits that pertain to the coding standard. 

> This draft has been through several revision rounds already, trying to
> take many aspects into account while still not imposing rules that are
> to strict to allow future development of the server.  We would very
> much like to have feedback from the MySQL development community on
> this draft.

When and how do we set the bar for the new components and features
to follow these guidelines?

We will be transitioning indefinitely unless we make
sure that all new code adheres to the new standard.

> High-level structure
> ====================
> This in turn
> requires the packages to provide the necessary information so that the
> build frame can do its job.

<cut>

> Components
> ==========
> 
> A component consist of a set of header files and a set of associated
> C/C++ files. The component is the smallest unit of the physical
> design.

How does component and package dependencies work?

Perhaps it is part of a separate document, describing the build
system, but I think it's necessary to mention the concept
here: part of adding a new component or package is to specify its
dependencies.

What considerations should one have when adding a
new component to the package, especially when it requires 
a change in package dependency tree?

Do we allow recursive dependencies?

Do we support the notion of component or package
versions or we assume that all packages have the
same version? 

Perhaps in the first approximation we don't need to bother. But
long term, packages such as a storage engine or libmysql will have
a version independent of the server version, and we will need to 
address the compatibility issue.

How strict do we want to be in enforcing the structure of a
package? What if the package has historically different
conventions for component management?

> Typically, each component consists of a header file and a C/C++ file
> with a common base name, for example "parser.h" and
> "parser.cc". However, there are some cases where it makes sense to
> have multiple header files for a component and cases when it makes
> sense to have multiple source files.
> 
> - Using several header files can be used to present multiple
>   interfaces into a single component.

Later on you advocate use of forward declarations.
Additionally you say that all names and declarations should be
in the component code, not in the user code.

I think it boils down to requiring a package to export forward
declaration header files in addition to component headers. 

> Packages
> ========
> 
> Packages are collections of components that serves a common purpose.
> This formulation is deliberately not exact since what actually makes
> sense to turn into a package vary from case to case. However, the
> following issues should be considered when deciding whether a
> candidate package makes sense as a package:
> 
> - Can the candidate package be released independently of the rest of
>   the server? If not, i.e., changes to this package is likely to
>   require changes to other packages, then maybe it should not be a
>   package.
> 
>   Releasing here does *not* mean distributing the code in isolation,
>   it means releasing, e.g., a new version of the package for use with
>   the rest of the server.

Here you mention the concept of package version without having
introduced it.

In addition to good common sense reasoning here, perhaps it makes
sense to follow the letter of Lacos here, and introduce a strict
notation; define the notion of a class, header, component and package
dependency and specify that the metric of "minimal unnecessary
class/header/component/package dependencies" as the key criteria
in splitting and merging functionality.

> - Is the candidate package very small, e.g., a single component? In
>   this case it might make sense to group several such candidate
>   packages with similar purpose into a single package.
> 
>   A typical example would be support for individual character sets,
>   that does not make sense to place in a single package each, but is
>   sensible as a package of "character set information".
> 
> 
> Package naming and structure
> ----------------------------
> 
> Each package is represented as a directory. The basic assumption is
> that everything related to a package should be placed in the
> directory. This includes, but is not limited to: header files, source
> files, and unit tests.
> 
> Basic goals and assumptions are:
> 
> - Changes in the package internals should not inadvertently affect
>   other packages that use the package
> 
> - It shall be possible to support third-party solutions as package in
>   the package structure and shall not require re-organization to fit
>   the package structure
> 
> The package directories will be placed in a directory alongside the
> ``sql/`` directory. Apart from that, all packages are placed at the
> same level. We are placing the packages in a new directory to be able
> to distinguish between "unorganized" and "organized" code.
> 
> The following package directories are proposed (some directories
> already exists and almost have the basic structure proposed):
> 
>     ========== ==============================================
>     Package    Purpose
>     ========== ==============================================
>     storage/   Storage engines
>     server/    Server modules
>     common/    Common utilities
>     ========== ==============================================

You refer to sql/ and server/ directories meaning the
same thing. Perhaps it is easier to just say that normally each
package is stored at the top level of the directory structure,
unless it falls into one of the predefined categories, such as 
a storage engine or a part of the core server.

> In order to use an interface of a package, the header file is included
> using the form:
> 
>     #include "package_name/interface.h"

In other words, I always say 
#include "falcon/falcon.h", even if falcon is in storage?


I think this document is large enough to justify introduction of a
summary that only contains the suggested changes and omits the
rationale and discussion. I'm looking forward to us moving forward
with this proposal.

-- 
Thread
RFC: draft of physical structure of server codeMats Kindahl11 Jun
  • Re: RFC: draft of physical structure of server codeKonstantin Osipov16 Jun
    • Re: RFC: draft of physical structure of server codeMats Kindahl16 Jun
  • Re: RFC: draft of physical structure of server codeMARK CALLAGHAN16 Jun
    • Re: RFC: draft of physical structure of server codeMats Kindahl16 Jun
      • Re: RFC: draft of physical structure of server codeMARK CALLAGHAN16 Jun