The cl-mongo-id Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-mongo-id Reference Manual

This is the cl-mongo-id Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 03:50:12 2022 GMT+0.

Table of Contents


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.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-mongo-id

A library for the creation/parsing of MongoDB Object IDs

Author

Andrew Lyon <orthecreedence@gmail.com>

License

MIT

Version

0.1.0

Dependencies
  • bordeaux-threads (system).
  • md5 (system).
  • local-time (system).
  • secure-random (system).
Source

cl-mongo-id.asd.

Child Component

mongo-id.lisp (file).


3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 cl-mongo-id/cl-mongo-id.asd

Source

cl-mongo-id.asd.

Parent Component

cl-mongo-id (system).

ASDF Systems

cl-mongo-id.


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

Source

cl-mongo-id.asd.

Parent Component

cl-mongo-id (system).

Packages

cl-mongo-id.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-mongo-id

Source

mongo-id.lisp.

Nickname

mongoid

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Ordinary functions

Function: get-hostname (oid &key bytes)
Package

cl-mongo-id.

Source

mongo-id.lisp.

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.

Function: get-pid (oid &key bytes)
Package

cl-mongo-id.

Source

mongo-id.lisp.

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.

Function: oid (&optional id)

Generate a mongo id, in byte vector format.

Package

cl-mongo-id.

Source

mongo-id.lisp.

Function: oid-str (oid)

Given a vector ID, convert it to a string.

Package

cl-mongo-id.

Source

mongo-id.lisp.


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *id-inc*
Package

cl-mongo-id.

Source

mongo-id.lisp.

Special Variable: *id-inc-lock*
Package

cl-mongo-id.

Source

mongo-id.lisp.

Special Variable: *random-value*
Package

cl-mongo-id.

Source

mongo-id.lisp.


Previous: , Up: Internals   [Contents][Index]

5.2.2 Ordinary 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.

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.

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.

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.

Function: get-current-timestamp ()

Get current unix timestamp.

Package

cl-mongo-id.

Source

mongo-id.lisp.

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.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts