r3/README.md

186 lines
5 KiB
Markdown
Raw Normal View History

2014-05-14 12:18:59 -04:00
R3
2014-05-11 18:52:36 -04:00
================
2014-05-16 21:38:21 -04:00
R3 is an URL router library with high performance, thus, it's implemented in C.
2014-05-16 08:11:59 -04:00
It compiles your route paths into a prefix trie.
By using the constructed prefix trie in the start-up time, you can dispatch
2014-05-16 07:17:59 -04:00
routes with efficiency.
2014-05-11 18:52:36 -04:00
2014-05-16 08:11:59 -04:00
Requirement
-----------------------
2014-05-16 21:38:21 -04:00
* autoconf
* automake
2014-05-16 08:11:59 -04:00
* check
* pcre
* jemalloc
2014-05-17 21:16:47 -04:00
* graphviz version 2.38.0 (20140413.2041)
2014-05-16 08:11:59 -04:00
2014-05-11 20:24:22 -04:00
Pattern Syntax
-----------------------
/blog/post/{id} use [^/]+ regular expression by default.
/blog/post/{id:\d+} use `\d+` regular expression instead of default.
2014-05-11 18:52:36 -04:00
2014-05-16 03:29:25 -04:00
C API
------------------------
```c
2014-05-17 22:29:36 -04:00
#include <r3.h>
2014-05-16 03:29:25 -04:00
// create a router tree with 10 children capacity (this capacity can grow dynamically)
2014-05-16 06:57:36 -04:00
n = r3_tree_create(10);
2014-05-16 03:29:25 -04:00
int route_data = 3;
// insert the route path into the router tree
2014-05-18 01:45:29 -04:00
r3_tree_insert_pathl(n , "/zoo" , strlen("/zoo") , NULL, &route_data );
r3_tree_insert_pathl(n , "/foo/bar" , strlen("/foo/bar") , NULL, &route_data );
r3_tree_insert_pathl(n , "/bar" , strlen("/bar") , NULL, &route_data );
r3_tree_insert_pathl(n , "/post/{id}" , strlen("/post/{id}") , NULL, &route_data );
2014-05-18 02:42:02 -04:00
r3_tree_insert_pathl(n , "/user/{id}" , strlen("/user/{id:\\d+}") , NULL, &route_data );
2014-05-16 03:29:25 -04:00
// let's compile the tree!
2014-05-16 06:57:36 -04:00
r3_tree_compile(n);
2014-05-16 03:29:25 -04:00
// dump the compiled tree
2014-05-16 06:57:36 -04:00
r3_tree_dump(n, 0);
2014-05-16 03:29:25 -04:00
// match a route
2014-05-18 01:45:29 -04:00
node *matched_node = r3_tree_match(n, "/foo/bar", strlen("/foo/bar"), NULL);
2014-05-16 03:29:25 -04:00
matched_node->endpoint; // make sure there is a route end at here.
int ret = *( (*int) matched_node->route_ptr );
```
### Routing with conditions
```c
2014-05-18 02:14:04 -04:00
// create the match entry for capturing dynamic variables.
match_entry * entry = match_entry_create("/foo/bar");
entry->request_method = METHOD_GET;
// create a router tree with 10 children capacity (this capacity can grow dynamically)
n = r3_tree_create(10);
int route_data = 3;
2014-05-18 02:14:04 -04:00
// define the route with conditions
route *r1 = route_create("/blog/post");
r1->request_method = METHOD_GET | METHOD_POST; // ALLOW GET OR POST
2014-05-18 02:14:04 -04:00
// insert the route path into the router tree
r3_tree_insert_route(n, r1, NULL, &route_data );
r3_tree_compile(n);
node *matched_node = r3_tree_match(n, "/foo/bar", strlen("/foo/bar"), entry);
matched_node->endpoint; // make sure there is a route end at here.
if (matched_node->routes) {
2014-05-18 02:14:04 -04:00
// find the route with matched condition
route *c = r3_node_match_route(m, entry);
c->data; // get the data from matched route
}
```
2014-05-16 03:29:25 -04:00
2014-05-11 18:52:36 -04:00
2014-05-16 07:17:59 -04:00
Benchmark
-----------------------
The routing benchmark from stevegraham/rails' PR <https://github.com/stevegraham/rails/pull/1>:
omg 10462.0 (±6.7%) i/s - 52417 in 5.030416s
And here is the result of the router journey:
omg 9932.9 (±4.8%) i/s - 49873 in 5.033452s
r3 uses the same route path data for benchmarking, and here is the benchmark:
2014-05-16 21:41:00 -04:00
3 runs, 5000000 iterations each run, finished in 1.308894 seconds
11460057.83 i/sec
2014-05-16 07:17:59 -04:00
2014-05-16 21:41:00 -04:00
The matching speed of r3 is 1153+ times faster than rails' trie router.
2014-05-16 07:17:59 -04:00
2014-05-16 07:19:10 -04:00
### The benchmarking route paths
2014-05-16 07:18:47 -04:00
The route path generator is from <https://github.com/stevegraham/rails/pull/1>:
```ruby
#!/usr/bin/env ruby
arr = ["foo", "bar", "baz", "qux", "quux", "corge", "grault", "garply"]
paths = arr.permutation(3).map { |a| "/#{a.join '/'}" }
paths.each do |path|
puts "r3_tree_insert_path(n, \"#{path}\", NULL);"
end
```
2014-05-17 20:19:32 -04:00
Rendering routes with graphviz
-------------------------------
The `test_gvc_render_file` API let you render the whole route trie into a image.
2014-05-17 20:21:09 -04:00
![Imgur](http://i.imgur.com/J2LdzeK.png)
2014-05-17 20:19:32 -04:00
Or you can even export it with dot format:
```dot
digraph g {
graph [bb="0,0,205.1,471"];
node [label="\N"];
"{root}" [height=0.5,
pos="35.097,453",
width=0.97491];
"#1" [height=0.5,
pos="35.097,366",
width=0.75];
....
```
2014-05-11 18:52:36 -04:00
Use case in PHP
-----------------------
```php
// Here is the paths data structure
$paths = [
2014-05-13 04:13:20 -04:00
'/blog/post/{id}' => [ 'controller' => 'PostController' , 'action' => 'item' , 'method' => 'GET' ] ,
'/blog/post' => [ 'controller' => 'PostController' , 'action' => 'list' , 'method' => 'GET' ] ,
'/blog/post' => [ 'controller' => 'PostController' , 'action' => 'create' , 'method' => 'POST' ] ,
'/blog' => [ 'controller' => 'BlogController' , 'action' => 'list' , 'method' => 'GET' ] ,
2014-05-11 18:52:36 -04:00
];
2014-05-16 07:13:24 -04:00
$rs = r3_compile($paths, 'persisten-table-id');
$ret = r3_dispatch($rs, '/blog/post/3' );
2014-05-11 18:52:36 -04:00
list($complete, $route, $variables) = $ret;
2014-05-16 07:13:24 -04:00
// matched conditions aren't done yet
list($error, $message) = r3_validate($route); // validate route conditions
2014-05-11 18:52:36 -04:00
if ( $error ) {
echo $message; // "Method not allowed", "...";
}
```
2014-05-16 08:35:16 -04:00
Install
2014-05-16 08:11:59 -04:00
----------------------
2014-05-17 20:13:58 -04:00
sudo apt-get install check libpcre3 libpcre3-dev libjemalloc-dev libjemalloc1 build-essential libtool automake autoconf graphviz-dev graphviz
2014-05-16 21:38:21 -04:00
./autogen.sh
2014-05-17 03:33:12 -04:00
./configure && make
2014-05-16 21:38:21 -04:00
make check # run tests
2014-05-16 08:35:16 -04:00
sudo make install
2014-05-16 08:11:59 -04:00
2014-05-17 21:31:08 -04:00
### Enable Graphviz
2014-05-16 21:38:21 -04:00
2014-05-17 21:31:08 -04:00
./configure --enable-graphviz
2014-05-16 21:38:21 -04:00
2014-05-17 22:28:19 -04:00
License
--------------------
This software is released under MIT License.