The cl-mongo-id Reference Manual

Table of Contents

The cl-mongo-id Reference Manual

This is the cl-mongo-id Reference Manual, version 0.1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 10:23:38 2020 GMT+0.

1 Introduction

cl-mongo-id

This is a simple library for creating/handling MongoDB's ObjectIDs. It works by grabbing key pieces of info (unix timestamp, hostname, process pid, global "inc" value) and creating a new ObjectID as a 12-byte array #(79 151 129 ...)

It aims to be as cross-platform/implementation as possible. If you find you're unable to run it on your specific platform, please let me know and I'll do whatever I can to fix it!

Usage

Install

(ql:quickload :cl-mongo-id)

Create byte array from string id:

(mongoid:oid "4f9638d834322b9531000005")  ->
    #(79 150 56 216 52 50 43 149 49 0 0 5)

Create new id using MongoDB ObjectID specification:

(mongoid:oid)  ->
    #(79 150 62 92 61 196 44 20 228 0 0 0)

Grab a string representation of an ObjectID:

(mongoid:oid-str (mongoid:oid))  ->
    "4F97001C3DC42C14E4000050"

Usage with cl-mongo

The cl-mongo-id library can be used with cl-mongo. There is just one caveat: You must import the make-bson-oid function from the cl-mongo package before you can use the two together.

(import 'cl-mongo::make-bson-oid)

(with-mongo-connection (:host "127.0.0.1" :db "test")
  ;; querying a document of a known id
  (db.find "mycoll" (kv "_id" (make-bson-oid :oid (mongoid:oid "4f9638d834322b9531000005"))))

  ;; creating a new document with an oid
  (let ((doc (make-document :oid (make-bson-oid :oid (mongoid:oid)))))
    (db.save "mycoll" doc)))

Thread safe

cl-mongo-id is built to be thread-safe (specifically the inc value). This means you can create ID's via (oid) from several different threads without problems, and your inc value will be unique between all of them.

Helper functions

cl-mongo-id has some helper functions that may be useful to you for either debugging or grabbing values from your IDs.

Note that all of the following helper functions take a keyword argument :bytes, which if set to T will return the raw bytes of that portion of the ID and not convert them to an integer.

get-timestamp

Get the unix timestamp from a Mongo Object ID:

(mongoid:get-timestamp (oid "4f96f9fa3dc42c14e400004e"))  ->
    1335294458

get-pid

Get the PID the ID was created under:

(mongoid:get-pid (oid "4f96f9fa3dc42c14e400004e"))  ->
    5348

get-hostname

Get the int value corresponding to the first three bytes of the MD5 of the hostname the ID was created on:

(mongoid:get-hostname (oid "4f96f9fa3dc42c14e400004e"))  ->
    4047916
(mongoid:get-hostname (oid "4f96f9fa3dc42c14e400004e") :bytes t)  ->
    #(61 196 44)

get-inc

Get the ID's "inc" value:

(mongoid:get-inc (oid "4f96f9fa3dc42c14e400004e"))  ->
    78

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-mongo-id

Author

Andrew Lyon <orthecreedence@gmail.com>

License

MIT

Description

A library for the creation/parsing of MongoDB Object IDs

Version

0.1.0

Dependencies

• bordeaux-threads
• md5
• local-time

Source

cl-mongo-id.asd (file)

Component

mongo-id.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-mongo-id.asd

Location

cl-mongo-id.asd

Systems

cl-mongo-id (system)

3.1.2 cl-mongo-id/mongo-id.lisp

Parent

cl-mongo-id (system)

Location

mongo-id.lisp

Packages

cl-mongo-id

Exported Definitions

• get-hostname (function)
• get-inc (function)
• get-pid (function)
• get-timestamp (function)
• oid (function)
• oid-str (function)

Internal Definitions

• *id-inc* (special variable)
• *id-inc-lock* (special variable)
• convert-hex-vector (function)
• convert-vector-int (function)
• create-new-id (function)
• get-current-hostname (function)
• get-current-pid (function)
• get-current-timestamp (function)
• get-inc-val (function)

4 Packages

Packages are listed by definition order.

4.1 cl-mongo-id

Source

mongo-id.lisp (file)

Nickname

mongoid

Use List

common-lisp

Exported Definitions

• get-hostname (function)
• get-inc (function)
• get-pid (function)
• get-timestamp (function)
• oid (function)
• oid-str (function)

Internal Definitions

• *id-inc* (special variable)
• *id-inc-lock* (special variable)
• convert-hex-vector (function)
• convert-vector-int (function)
• create-new-id (function)
• get-current-hostname (function)
• get-current-pid (function)
• get-current-timestamp (function)
• get-inc-val (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Functions

Function: get-hostname OID &key BYTES

Grab the hostname int out of a vector oid. Passing :bytes t will return an array of bytes corresponding to the hostname part of the ID instead of parsing it as an integer.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-inc OID &key BYTES

Grab the inc value out of a vector oid. Passing :bytes t will return an array of bytes corresponding to the inc value of the ID instead of parsing it as an integer.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-pid OID &key BYTES

Grab the pid out of a vector oid. Passing :bytes t will return an array of bytes corresponding to the PID part of the ID instead of parsing it as an integer.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-timestamp OID &key BYTES

Grab the timestamp out of a vector oid. Passing :bytes t will return an array of bytes corresponding to the timestamp part of the ID instead of parsing it as an integer.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: oid &optional ID

Generate a mongo id, in byte vector format.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: oid-str OID

Given a vector ID, convert it to a string.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *id-inc*

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Special Variable: *id-inc-lock*

Package

cl-mongo-id

Source

mongo-id.lisp (file)

5.2.2 Functions

Function: convert-hex-vector HEX-STRING

Takes a hex string, IE 4f2b8096 and converts it into a byte array: 4f2b8096 -> #(79 43 128 150)
Hex string *must* have even number of bytes.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: convert-vector-int VECTOR

Convert a byte array to an integer: #(79 150 243 81) -> 1335292753

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: create-new-id ()

Create a brand-spankin-new ObjectId using the current timestamp/inc values, along with hostname and process pid.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-current-hostname ()

Get hostname of machine.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-current-pid &key IF-NOT-EXISTS-RETURN

Get the current process’ PID. This function does it’s best to be cross- implementation. If it isn’t able to grab the PID from the system, it defaults to returning whatever value is passed into the :if-not-exists-return key.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-current-timestamp ()

Get current unix timestamp.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-inc-val ()

Thread-safe method to get current ObjectId inc value. Takes an optional timestamp value to calculate inc for.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types