Code Monkey home page Code Monkey logo

lua-resty-jit-uuid's Introduction

lua-resty-jit-uuid

Module Version Build Status Coverage Status

A pure LuaJIT (no dependencies) UUID library tuned for performance.

Table of Contents

Motivation

This module is aimed at being a free of dependencies, performant and complete UUID library for LuaJIT and ngx_lua.

Unlike FFI and C bindings, it does not depend on libuuid being available in your system. On top of that, it performs better than most (all?) of the generators it was benchmarked against, FFI bindings included.

Finally, it provides additional features such as UUID v3/v4/v5 generation and UUID validation.

See the Benchmarks section for comparisons between other UUID libraries for Lua/LuaJIT.

Back to TOC

Usage

LuaJIT:

local uuid = require 'resty.jit-uuid'

uuid.seed()        ---> automatic seeding with os.time(), LuaSocket, or ngx.time()

uuid()             ---> v4 UUID (random)
uuid.generate_v4() ---> v4 UUID

uuid.generate_v3() ---> v3 UUID (name-based with MD5)
uuid.generate_v5() ---> v5 UUID (name-based with SHA-1)

uuid.is_valid()    ---> true/false (automatic JIT PCRE or Lua patterns)

OpenResty:

http {
    init_worker_by_lua_block {
        local uuid = require 'resty.jit-uuid'
        uuid.seed() -- very important!
    }

    server {
        location / {
            content_by_lua_block {
                local uuid = require 'resty.jit-uuid'
                ngx.say(uuid())
            }
        }
    }
}

Note: when generating v4 (random) UUIDs in ngx_lua, it is very important that you seed this module in the init_worker phase. If you do not, your workers will generate identical UUID sequences, which could lead to serious issues in your application. The seeding requirement also applies in uses outside of ngx_lua, although seeding is less delicate in such cases. Additionally, you should be weary about the usage of the lua_code_cache directive: if Lua code cache is disabled, all sequences of UUIDs generated during subsequent requests will be identical, unless this module is seeded for every request. Just like disabling Lua code cache, such behavior would be considered an ngx_lua anti-pattern and you should avoid it.

Back to TOC

Installation

This module can be installed through Luarocks:

$ luarocks install lua-resty-jit-uuid

Or via opm:

$ opm get thibaultcha/lua-resty-jit-uuid

Or can be manually copied in your LUA_PATH.

Back to TOC

Documentation

Documentation is available online at http://thibaultcha.github.io/lua-resty-jit-uuid/.

Back to TOC

Benchmarks

This module has been carefully benchmarked on each step of its implementation to ensure the best performance for OpenResty and plain LuaJIT. For example, UUID validation will use JIT PCRE over Lua patterns when possible.

The bench.lua file provides benchmarks of UUID generation for several popular UUID libraries.

Run make bench to run them:

LuaJIT 2.1.0-beta1 with 1e+06 UUIDs
UUID v4 (random) generation
1. resty-jit-uuid   took:   0.064228s    0%
2. FFI binding      took:   0.093374s   +45%
3. C binding        took:   0.220542s   +243%
4. Pure Lua         took:   2.051905s   +3094%

UUID v3 (name-based and MD5) generation if supported
1. resty-jit-uuid   took:   1.306127s

UUID v5 (name-based and SHA-1) generation if supported
1. resty-jit-uuid   took:   4.834929s

UUID validation if supported (set of 70% valid, 30% invalid)
1. resty-jit-uuid (JIT PCRE enabled)    took:   0.223060s
2. FFI binding                          took:   0.256580s
3. resty-jit-uuid (Lua patterns)        took:   0.444174s

Note: UUID validation performance in ngx_lua (JIT PCRE) can be greatly improved by enabling lua-resty-core.

Back to TOC

Contributions

Suggestions improving this module's or the benchmarks' performance (of any benchmarked library) are particularly appreciated.

Back to TOC

License

Work licensed under the MIT License.

Back to TOC

lua-resty-jit-uuid's People

Contributors

jprjr avatar spacewander avatar thibaultcha avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.