【hyperscan】示例解读 simplegrep

示例位置: <hyperscan source>/examples/simplegrep.c
参考：http://01org.github.io/hyperscan/dev-reference/api_files.html

1. 概述

此示例实现一个grep的简化版本：指定一个正则表达式和文件，执行后依次输出匹配位置。

但这个简单示例并不支持从stdin读取数据，也不支持grep那丰富的命令行参数。

simplegrep演示了以下hyperscan概念：

单个模式的编译
使用最简单的hs_compile接口，仅支持一个正则表达式。支持多个表达式同时编译的API是hs_compile_multi
Block方式的模式匹配
在单个数据块上进行搜索匹配；更复杂的是在流(stream)上进行匹配，它可以跨数据块进行模式匹配
临时数据(scratch)的分配与使用
hyperscan在匹配时需要一块临时数据（记为D），调用者需要保证在同一时刻只有一个hs_scan接口使用同一D，但并不要求连续的hs_can调用必须使用同一个D。由于D的分配代价昂贵，为了性能考虑，用户最好在运行前就分配好D并在运行时重用它。

2. 源码解读

这个示例非常简单，这里只解读表达式编译和匹配两部分的代码，读取数据文件等代码忽略。

2.1 编译正则表达式(compile)

进行匹配之前，首先需要编译正则表达式，生成hs_database_t。

    hs_database_t *database;
    hs_compile_error_t *compile_err;
    if (hs_compile(pattern, HS_FLAG_DOTALL, HS_MODE_BLOCK, NULL, &database,
                   &compile_err) != HS_SUCCESS) {
        fprintf(stderr, "ERROR: Unable to compile pattern \"%s\": %s\n",
                pattern, compile_err->message);
        hs_free_compile_error(compile_err);
        return -;
    }

hs_compile的原型是

hs_error_t hs_compile(const char * expression, 
                      unsigned int flags, 
                      unsigned int mode, 
                      const hs_platform_info_t * platform, 
                      hs_database_t ** db, 
                      hs_compile_error_t ** error)

其中，expression是正则表达式字符串；flags用来控制正则的行为，比如忽略大小写，使.包含换行等；mode确定了生成database的格式，主要有BLOCK，STREAM和VECTOR三种，每一种模式的database只能由相应的scan接口使用；platform用来指定此database的目标平台（主要是一些CPU特性），为NULL表示目标平台与当前平台一致；db用来保存编译后的database；error接收错误信息。

2.2 进行匹配(scan)

首先分配好每次匹配需要用的临时数据(scratch)。

hs_scratch_t *scratch = NULL;
    if (hs_alloc_scratch(database, &scratch) != HS_SUCCESS) {
        fprintf(stderr, "ERROR: Unable to allocate scratch space. Exiting.\n");
        free(inputData);
        hs_free_database(database);
        return -;
    }

接下来进行匹配(scan）。

if (hs_scan(database, inputData, length, , scratch, eventHandler,
                pattern) != HS_SUCCESS) {
        fprintf(stderr, "ERROR: Unable to scan input buffer. Exiting.\n");
        hs_free_scratch(scratch);
        free(inputData);
        hs_free_database(database);
        return -;
    }

hs_scan的原型是

hs_error_t hs_scan(const hs_database_t * db, 
                   const char * data, 
                   unsigned int length, 
                   unsigned int flags, 
                   hs_scratch_t * scratch, 
                   match_event_handler onEvent, 
                   void * context)

其中，db就是上一步编译的databas；data和length分别是要匹配的数据和数据长度；flags用来在未来版本中控制函数行为，目前未使用；scratch是匹配时要用的临时数据，之前已经分配好；onEvent非常关键，即匹配时调用的回调函数，由用户指定；context是用户自定义指针。

匹配回调函数的原型是

typedef (* match_event_handler)(unsigned int id, 
                                unsigned long long from, 
                                unsigned long long to, 
                                unsigned int flags, 
                                void *context)

其中，id是命中的正则表达式的ID，对于使用hs_compile编译的唯一表达式来说，此值为0；如果在编译时指定了相关模式选项(hs_compile中的mode参数），则此值将会设为匹配特征的起始位置，否则会设为0；to是命中数据的下一个字节的偏移；flags目前未用；context是用户自定义指针。

返回值为非0表示停止匹配，否则继续；在匹配的过程中，每次命中时都将同步调用匹配回调函数，直到匹配结束。

本例中的回调函数是

static int eventHandler(unsigned int id, unsigned long long from,
                        unsigned long long to, unsigned int flags, void *ctx) {
    printf("Match for pattern \"%s\" at offset %llu\n", (char *)ctx, to);
    return ;
}

输出了正则表达式和其匹配的位置（命中数据的下一个字节在数据中的偏移值）。

2.3 清理资源

程序结束后，应清理相关数据，释放内存。

    hs_free_scratch(scratch);
    free(inputData);
    hs_free_database(database);

3. 编译运行

编译之前，我已经通过make install将hyperscan头文件和静态库安装在了/usr/local相关目录中。

gcc -o simplegrep simplegrep.c -lhs -lstdc++ -lm

注意链接stdc++和math库（lstdc++ -lm)。如果是链接动态库，不需要加-lstdc++ -lm。

运行，在另一示例代码pcapscan.cc中匹配/[f|F]ile/：

./simplegrep '[f|F]ile' pcapscan.cc
Scanning  bytes with Hyperscan
Match for pattern "[f|F]ile" at offset
.....（略，共45次匹配）

用grep命令验证结果

grep -o '[f|F]ile' pcapscan.cc | wc -l

OK，也是45次。