API空间

你不记得在大学里听说过“API Spaces”的原因是我刚刚创造了这个概念，作为这篇文章的标题。

我们需要一个名称来描述API与命名空间之间的冲突。

在他们职业生涯的某个时候，大多数C程序员都会学到 j0 ， j1 ， y0 和 y1 是要避免的名称，而 j2 和 y2 最多，但不包括 jn 和 yn 都很好。

原因是，当我还是个孩子的时候，有人认为如果数学库支持贝塞尔函数会非常好，而没有考虑到 <math.h> 作为API，它必须与许多其他API共存于C语言的平面命名空间中。

面向对象编程的一大吸引人之处在于它恰恰解决了这个问题：没有人会感到困惑 car->push() 和 stack->push() 。

但Varnish是用C编写的，它有一个平面命名空间，我们必须接受它。

从一开始，我们就通过将VTLA前缀分配给各种代码块来定义平面命名空间中的地籍边界。

VSB_something 与我们从FreeBSD采用的sbuf有关， VGC_something 是VCC生成的C源程序等等。

大多数情况下，我们使用的是V前缀，由于某种原因，这个前缀在其他地方几乎都没有使用过，但我们也有明显的例外。 WS_something 例如，对于工作空间。

只要所有的C代码都在项目中，功能原型的不一致和精确位置就不会有太大影响，这只是“你必须知道的事情”。

现在我们有了VMOD，更重要的是，我们想要为VMOD提供一些表面上的API稳定性，我们有很多排序和一些重命名要做，以便在我们的平面命名空间和我们的包含文件中清楚地描述API。

弗雷德里克·P·布鲁克斯在他的经典之作《神话中的人月》中指出，这就是程序产品和程序产品之间的区别，他提出，努力需要三次努力，从前者到后者。

在花了几个星期的时间完成我认为将是三天的任务后，我怀疑他的估计被低估了。

我现在将尝试列出我认为未来我们在API和名称空间共享方面的政策，但请理解，在这一点上，这主要是一个令人向往的目标。

通用命名空间规则

  1. 每个API或以其他方式隔离的代码段都有一个以下划线结尾的唯一前缀， (VSB_ ， V1F_ 等)

  2. 公共符号具有大写前缀。

  3. 专用符号使用小写前缀，两者均为 static 符号，以及在向同一代码段中的其他源文件公开时。

  4. 福利之友符号在前缀后面有额外的下划线： FOO__bar() 并且只能在获得明确许可的情况下使用，并应在相关的#INCLUDE文件中明确记录。

VMOD API/ABI级别

Vmod可以针对三个API/ABI级别之一编写，分别调用 VRT ， PACKAGE 和 SOURCE ，将在下面详细定义。

VMOD将其自身限制为 VRT API/ABI获得了最大的稳定性，我们希望，它将在许多Varnish的主要和次要版本上无需重新编译即可工作。

一个VMOD使用 PACKAGE API，可能会继续在Varnish的次要版本中工作，但通常需要重新编译才能用于新的Varnish主要版本。

一个VMOD使用 SOURCE API是针对一个特定版本的Varnish进行编译的，在重新编译之前不能与另一个版本一起使用。

VMOD VRT API/ABI

这个API空间也可以称为‘inline’，因为它基本上就是您在VCC生成的C源代码中看到的：

包括允许的文件：

#include "vdef.h"
#include "vrt.h"
#include "vrt_obj.h"
#include "vcl.h"

任何私有和福利之友符号都是VMOD的禁区(它通常是VCC编译代码所需要的东西，如果你搞砸了它很可能会崩溃)。

这个 "vrt.h" 包含两个#定义，它们共同定义了此接口的级别：

#define VRT_MAJOR_VERSION       6U
#define VRT_MINOR_VERSION       2U

这些内容的快照将自动编译到VMOD共享库中，并在VCL编译器导入VMOD时检查它们的兼容性。

VMOD包API/ABI

此API空间提供对 VRT API空间以及varnishd中公开和支持的其他API。

包括允许的文件：

#include "cache.h"            // NB: includes vdef.h and vrt.h
#include "cache_backend.h"
#include "cache_director.h"
#include "cache_filter.h"
#include "waiter/waiter.h"

任何私人和福利之友的符号都是VMOD的禁区。

除了两部分的VRT版本外， "cache.h" 将包含此API级别的两个#定义。

#define PACKAGE_MAJOR_VERSION       1U
#define PACKAGE MINOR_VERSION       3U

将检查这些组件的编译时快照，以及它们的VRT近亲在VMOD导入时的兼容性。

VMOD源API/ABI

此API空间提供了对varnishd的私有部分的访问，强烈建议您使用它，除非您必须这样做，

你可以#包括Varnish源码树中的任何文件，并使用你在其中找到的任何文件--但如果一切都以泪水告终，请不要哭着来找我们：这个窗口不退款。

源代码树中所有.h文件的哈希值将被编译到VMOD中，并将在VMOD导入时进行检查以完全匹配。

phk