首页 > ATS核心, ATS调优, 插件开发 > ATS插件开发基础

ATS插件开发基础

2013年6月13日     浏览数:8,515 发表评论 阅读评论

ATS插件开发基础

ATS插件开发需要提前了解ATS的插件的一些设计思想,以及系统提供的一些不同方向。我们将会介绍ATS的基础开发知识,以利于后续的插件开发课程讲解。

ATS的SDK文档,是了解ATS的核心设计、接口设计的很重要资料,甚至是老的PDF版本文档,都是非常非常有用的资料。以至于我经常建议完全不了解ATS核心代码的初学者也好好看看SDK文档,这里讲的很多基础知识,有利于对核心的深入理解。ATS的API以及核心插件接口设计是一个很庞大的工程,其设计思想我们很难一下消化掉,这里点出一些知识点供大家参考。如有纰漏、谬误之处,以SDK文档、代码注释、代码为准。

官方SDK文档

历史的SDK PDF文件

下一篇:手把手教你写plugin

ATS开发环境

名词解释

  • HTTP Transaction

    HTTP Transaction 是ATS特指http的处理流程,在ATS中,一个HTTP的请求的处理过程,叫做一个HTTP Transaction。ATS的很多API是以Transaction为核心的函数处理过程,也就赋予了这个过程以特殊的意义。在相关的API函数中,TSHttpTxn数据结构,以及以TSHttpTxn开头的API函数都是围绕这个处理流程来的。

  • HTTP SM

    HTTP SM 是一般是指ATS的主流程状态机,在ATS中,处理的流程是通过HTTP Transaction中的函数处理的,而状态数据是存储在HTTP SM中的。ATS核心主流程就是HTTP Transaction和HTTP SM的交互过程。

  • HTTP session

    HTTP session是指http会话,一般指一个请求交互过程,特指如客户端的一个请求,回源的一个请求,分别对应客户端和服务器端HTTP session。对照HTTP Transaction,我们对应的ATS一个用户请求引起的ATS HTTP Transaction,可以包含一个客户端 HTTP Session,0个或1个甚至多个回源 HTTP Session。

  • remap

    remap是ATS做URL rewrite的方式,也是ATS在配置文件设计方面的特殊部分。从功能上来讲,ATS的remap更像一个精简版本的Apache Httpd的rewrite模块。remap之所以重要,是因为它定义了一个很方便的API入口,我们可以通过remap系统,编写remap插件。

基础知识:

  • Continuation

    Continuation,从学术上应该是叫做Continuation的编程模型(方法),这个技术相当古老,后来微软围绕这个方案,改进出了coroutine的编程模型(方法),一定程度上来讲Continuation是整个异步回调机制的多线程事件编程基础。对应ATS中,Continuation是一个最最基础的抽象结构,后续的所有高级结构,如Action Event VC等都封装Continuation数据结构,我们先看Continuation结构的实际代码:

    class Continuation: private force_VFPT_to_top
    {
    public:
        ContinuationHandler handler;
        Ptr<proxymutex> mutex;
        LINK(Continuation, link);
    
        int handleEvent(int event = CONTINUATION_EVENT_NONE, void *data = 0) {
        return (this->*handler) (event, data);
        }
    
        Continuation(ProxyMutex * amutex = NULL);
    };
    

    Continuation主要包含:

    • handler:当前的Continuation处理函数。
    • mutex:Continuation的锁。
    • link:链接到其他Continuation的双链表。
    • handleEvent:接收event的代码和数据,并交给当前的处理函数处理。

    结构非常精炼,并不代表特殊含义。

    Continuation在API中的结构叫TSCont,是插件开发中最常用到的抽象之一,是多数API要求的参数结构。在插件编程中的主要用到的如blacklit-0中的代码:

    TSHttpHookAdd(TS_HTTP_OS_DNS_HOOK, TSContCreate(blacklist_plugin, NULL));
    

    这是一个hook函数,在TS_HTTP_OS_DNS_HOOK阶段,hook进去了blacklist_plugin(见下面代码),而blacklist_plugin 函数事实上只是一个事件处理的handler而以,这里通过TSContCreate转化为TSCont结构。通过这些API,插件开发者可以更关注业务流程实现,甚至都可以不用去理解ATS核心的复杂异步事件化机制,只需要照着例子来堆代码就好啦。

    static int
    blacklist_plugin(TSCont contp, TSEvent event, void *edata)
    {
      TSHttpTxn txnp = (TSHttpTxn) edata;
    
      switch (event) {
      case TS_EVENT_HTTP_OS_DNS:
        handle_dns(txnp, contp);
        return 0;
      case TS_EVENT_HTTP_SEND_RESPONSE_HDR:
        handle_response(txnp);
        return 0;
      default:
        break;
      }
      return 0;
    }
    
  • Action

    Action是一个抽象出来的,由处理机处理的异步任务模型。这个任务是可以在异步处理环境中允许撤销的。简单的以为可以说是一个可以撤销的函数机制?

    这个结构的主要用处是用来构建统一的Event系统,用在底层的iocore/中的网络以及磁盘IO等方面。当然,ATS的上层建筑更是依赖于它了。

    class Action
    {
    public:
        Continuation * continuation;
        Ptr</proxymutex><proxymutex> mutex;
        volatile int cancelled;
    
        virtual void cancel(Continuation * c = NULL) {
        if (!cancelled)
            cancelled = true;
        }
    
        void cancel_action(Continuation * c = NULL) {
        if (!cancelled)
            cancelled = true;
        }
    
        Continuation *operator =(Continuation * acont)
        {
        continuation = acont;
        if (acont)
            mutex = acont->mutex;
        else
            mutex = 0;
        return acont;
        }
    
        Action():continuation(NULL), cancelled(false) {
        }
    
        virtual ~ Action() {
        }
    };
    

    关于Action,有几个需要注意的地方:

    • Action是可以再入的
    • 撤销必须是由任务的callback处理机来做
    • 要撤销必须先拿到锁
    • Action是由处理机创建的,在完成或撤销的时候,也是由处理机负责的。状态机不能在Action完成或撤销后再访问它
  • Event

    Event是由Event处理机返回的一种Action。是可以用来调度出去从而异步处理的任务(Action)。event是不可再入的。由于它继承自Action,因此也具有可以撤销的机制,同时更可以在收到Event后处理或不处理而再调度出去,这个很乱啊:D

    Event的调度分为4种:

    • _imm:立即执行,这个模式讲会直接让Event进入待执行队列
    • _at:在未来某个具体时间,指定具体事件执行
    • _in:在未来某段时间后,指定具体多久之后执行
    • _every:每隔多长事件,让事件循环执行,类似cron等定时任务

      class Event:public Action
      {
      public:
      void schedule_imm(int callback_event = EVENT_IMMEDIATE);
      void schedule_at(ink_hrtime atimeout_at, int callback_event = EVENT_INTERVAL);
      void schedule_in(ink_hrtime atimeout_in, int callback_event = EVENT_INTERVAL);
      void schedule_every(ink_hrtime aperiod, int callback_event = EVENT_INTERVAL);
      void free();

      EThread *ethread;

      unsigned int in_the_prot_queue:1;
      unsigned int in_the_priority_queue:1;
      unsigned int immediate:1;
      unsigned int globally_allocated:1;
      unsigned int in_heap:4;
      int callback_event;

      ink_hrtime timeout_at;
      ink_hrtime period;

      void *cookie;

      Event();
      Event *init(Continuation * c, ink_hrtime atimeout_at = 0, ink_hrtime aperiod = 0);
      private:
      void *operator new(size_t size);
      Event(const Event &);
      Event & operator =(const Event &);

      public:
      LINK(Event, link);
      };

    关于Event结构,有如下几点需要注意:

    • 状态机只能在那个call-back线程中,发起调度,并且需要拿到continuation的锁。
    • 撤销机制与Action类似,也需要在call-back状态机拿到锁的情况下做。
    • 状态机中,Event事件的代码是需要全局统一的
  • VC

    VConnection是ATS核心、插件都常用的一种面向stream的数据抽象结构。主要可以理解为一个数据读写管道,在某些场景下,有点类似FD的效果。VConnection继承自continuation,也是会call-back到处理机处理的。这个基类是封装上层通信管道的基础。

    VConnection提供关键的几个接口:

    • do_io_read
    • do_io_write
    • do_io_close
    • do_io_shutdown
    • reenable 用来通知另一端可以实施下一步动作
    • set_continuation

      class VConnection:public Continuation
      {
      public:

      virtual ~ VConnection();

      virtual VIO *do_io_read(Continuation *c = NULL, int64_t nbytes = INT64_MAX, MIOBuffer *buf = 0) = 0;
      virtual VIO *do_io_write(Continuation *c = NULL,
      int64_t nbytes = INT64_MAX, IOBufferReader *buf = 0, bool owner = false) = 0;
      virtual void do_io_close(int lerrno = -1) = 0;
      virtual void do_io_shutdown(ShutdownHowTo_t howto) = 0;

      VConnection(ProxyMutex *aMutex);
      virtual void set_continuation(VIO *vio, Continuation *cont);
      virtual void reenable(VIO *vio);
      virtual void reenable_re(VIO *vio);

      virtual bool get_data(int id, void *data)
      {
      (void) id;
      (void) data;
      return false;
      }
      virtual bool set_data(int id, void *data)
      {
      (void) id;
      (void) data;
      return false;
      }

      public:
      int lerrno;
      };

    VConnection定义了一个可以串联的虚拟管道,可以让ATS在网络、状态机、磁盘间形成流式数据通信,是上层通信机制的很关键一环。

语言与接口

  • C API

    ATS默认的API是C API,即ts.h,这是C的API,据某人说用C++程序封装出C API很强大,不明觉历。

    ATS同时还有一些个非稳定的API,定义在:experimental.h

    还有2个API文件,默认并没有提供给大家

    • InkAPIHughes.h 为Hughes设计的Prefetch API,用到Prefetch功能的可以看看。
    • InkAPIPrivateIOCore.h 很底层的API,如锁、Buffer、网络包等,应该没有需要用到的必要。
  • C++ API

    LinkIn 公司为ATS添加了一套C++的API,需要在编译的时候加 --with-cpp11api 选项configure才行。

    C++ API包含:

    • ts-cpp11.h
    • ts-cpp11-headers.h

    这个API可能不够完备

ATS插件环境

  • ATS 插件模式

    • global:这种模式的插件,是会对全局有效,可以有效拦截整个流程,包括客户端建连过程。
    • remap:在用户请求经过remap完成后的阶段hook进去,是一个添加网站应用逻辑的地方。
  • ATS 插件模板
    • global
      • TBD 我希望能够用tsxs这个工具能够生成一些模板代码,正在整理中
    • remap
      • TBD

ATS核心流程

  • 流程
  • hook点

关于状态机

  • 主HttpSM

    HttpSM是指ATS的核心http流程状态机,即proxy/http/HttpSM.cc(.h)中定义的状态机,这是整个proxy业务的大状态机,所有的其他流程都是依附于(或关联于)这个状态机上的。如回源、读写cache等。当然这个文件也是目前ATS中最大的2个文件之一,以近万行的代码挑战你的能力。

    HttpSM相对插件开发者来说,几乎是不可见的,因为所有的插件都是hook到整个http流程中间来的。只有想看核心代码的同学才有意义。

  • 子状态机

    所谓子状态机,其实在ATS的事件系统里,到处都是,只要是做一个稍微复杂点的异步处理必然要引入一个状态机(processor)来做,相对来说这些都比较微型化。

    ATS的主HttpSM状态机并不是完全不可控制的,ATS允许你很大程度的自己定制自己的状态机,甚至绕过绝大多数HttpSM流程,这里可以参考的代码有:

    • Prefetch:proxy/Prefetch.cc(.h),这是一个做到核心中的transform插件,在用户访问html的时候,解析html并提取所有页面元素,主动发起回源以预取,提高用户感受。这里的核心是一个后台回源状态机,典型的设计可以参考。
    • example/protocol,这是一个完全脱离HttpSM的协议代码例子,这里定义了一个protocol插件,直接accept并且自己建立了自己的SM状态机,走自己的独立流程(TxnSM.c)。

ATS代码树

  • iocore

    IOcore系统是定义最核心的ATS基础模块,定义了底层的所有关键框架,这些模块和框架与业务系统相对独立,其中包括:

    • eventsystem 事件系统,定义了事件系统的调度机制、buffer管理系统等等
    • net 网络层,定义了网络处理的基础框架
    • aio 异步IO的实现,实现了类似于libc的AIO线程方案
    • cache 缓存与文件系统,管理磁盘存储、内存cache等
    • cluster 集群通信系统,解决集群数据交互协议RPC
    • dns DNS解析代码,我们需要在异步环境下做DNS的解析客户端
    • hostdb DNS缓存系统,解决了DNS的中间cache

    IOcore系统,代码逻辑相对隔离的还是不错的,因此各个模块是能够比较独立的理解和学习的。

  • proxy

    Proxy模块可以说是ATS的业务逻辑,也是traffic_server的主代码所在地。

    Proxy下有几个比较关键的模块:

    • logging:所谓的access日志模块
    • api:我们所说的API都是定义在这里的。(C++API放在lib目录下)
    • config:ATS的配置文件源文件目录
    • http:这是关键的状态机目录

    其他各种功能,都放在proxy/目录下,这里也是功能最多、最乱的一滩子啦。

  • cop

    cop是用来存放traffic_cop代码的,相对来说是最简单的代码啦。

  • mgmt

    这里存放的是traffic_manager代码。其中仍有许多需要清理的老代码残渣。

  • lib

    这里存放的是ATS的基础库,继承自原Inktomi++的仿C++标准库,ATS对外部库依赖比较少皆因这个库成型比较早,并且覆盖面比较全面。某人说这个就是C++标准库啊。话说当年(95-99年)ATS开发的时候,C++标准还在娘胎中吧?

    lib下有几个关键模块:

    • ts:即所说的ATS C++标准库
    • records:这个目录是stats|records系统的关键
  • example

    存放SDK介绍的,以及未介绍的所有插件参考代码。可以放心的说,ATS能够做的场景,在这个目录下都可以找到比较接近的例子。从这里的代码开始业务编程是很好的选择。

  • tools

    存放性能测试工具如http_load jtest工具以及状态跟踪工具tstop等

  • plugins

    存放所有公开到主代码的插件系统代码:

    • esi
    • cacheurl
    • regex_remap
    • 其他experimental插件
  • doc

    存放Admin手册、man手册等

  • rc

    init脚本等

分类: ATS核心, ATS调优, 插件开发 标签:
  1. 2013年6月13日18:40 | #1

    正在看代码,又学到不少东西。

  2. 2013年6月24日14:34 | #2

    豪哥,看了几遍官方文档VIO,VCONNECTION这些的使用还是不太明白。每个插件好像都用到了这些东西。能否再详细的介绍一下使用方法?

  3. tao_627
    2014年2月10日20:13 | #3

    很感谢豪哥心血积累的无私共享,有些东西说的很精辟,对很多关键而又易含混的概念说的很浅显易懂,比如这句,VConnection定义了一个可以串联的虚拟管道,可以让ATS在网络、状态机、磁盘间形成流式数据通信,是上层通信机制的很关键一环。至于领悟的程度,就只能靠个人的悟性和勤奋程度了。

  4. 2015年12月4日12:18 | #4

    很不错的分享,正在做ats的开发,很不错的分享;

  5. 木小南
    2016年10月10日15:22 | #5

    正在ats的入门阶段,很棒的资料,谢谢了。

  1. 本文目前尚无任何 trackbacks 和 pingbacks.