The cl-etcd Reference Manual

Table of Contents

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

The cl-etcd Reference Manual

This is the cl-etcd Reference Manual, version 0, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 03:45:27 2022 GMT+0.


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

1 Introduction

cl-etcd

Build Status

The purpose of cl-etcd is to simplify the writing of distributed applications in Common Lisp. etcd is a strongly consistent, distributed key-value store. At it's core is an implementation of the raft consensus algorithm. GC pauses in my lisp implementation of choice make it a poor choice for a lisp-based raft implementation, and so we run etcd as an asynchronous child process under lisp.

The cl-etcd package includes basic get-etcd and watch functions, as well as the convenience macro with-etcd to make it easy to start-up and shut-down your "embedded" etcd node. get-etcd is setf-able so you can easily modify the key-value store the Lisp way.

If you want to be notified about leader state changes on your node, supply the optional :on-leader and :on-follower lambdas, and they will be called when the node becomes a cluster leader or follower respectively.

Etcd is configured for auto-TLS communication between peers, meaning that the inter-node traffic will be encrypted with self-signed certificates. No form of authentication or encryption is currently performed between etcd and the client (the cl-etcd library code), however etcd is configured to only allow connections from localhost.

Here's a trivial example of a single node:

(with-etcd (etcd nil)
  (setf (get-etcd "hello" etcd) "world")
  (get-etcd "hello" etcd))

To be notified on state changes to leader or follower, do this:

(defun become-leader (etcd)
  (print "I'm the leader!"))

(defun become-follower (etcd)
  (print "I'm a follower!"))

(with-etcd (etcd nil :on-leader #'become-leader :on-follower #'become-follower)
  (setf (get-etcd "hello" etcd) "world")
  (get-etcd "hello" etcd))

A single instance is pretty useless, so let's make a 3-node cluster! The second argument to with-etcd is a hashtable of etcd arguments. The easiest way to populate this is through TOML config files. Let's make three config files like so...

config1.ini:

[etcd]
name = "infra0"
initial-advertise-peer-urls = "http://127.0.0.1:2380"
listen-peer-urls = "http://127.0.0.1:2380"
listen-client-urls = "http://127.0.0.1:2379"
advertise-client-urls = "http://127.0.0.1:2379"
initial-cluster = "infra0=http://127.0.0.1:2380,infra1=http://127.0.0.1:2480,infra2=http://127.0.0.1:2580"

config2.ini:

[etcd]
name = "infra1"
initial-advertise-peer-urls = "http://127.0.0.1:2480"
listen-peer-urls = "http://127.0.0.1:2480"
listen-client-urls = "http://127.0.0.1:2479"
advertise-client-urls = "http://127.0.0.1:2479"
initial-cluster = "infra0=http://127.0.0.1:2380,infra1=http://127.0.0.1:2480,infra2=http://127.0.0.1:2580"

config2.ini:

[etcd]
name = "infra2"
initial-advertise-peer-urls = "http://127.0.0.1:2580"
listen-peer-urls = "http://127.0.0.1:2580"
listen-client-urls = "http://127.0.0.1:2579"
advertise-client-urls = "http://127.0.0.1:2579"
initial-cluster = "infra0=http://127.0.0.1:2380,infra1=http://127.0.0.1:2480,infra2=http://127.0.0.1:2580"

Now, in each process, load the appropriate config file:

(defun become-leader (etcd)
  (setf (get-etcd "hello" etcd) "world"))

(let ((config (cdr (assoc :etcd (cl-toml:parse-file "config1.ini")))))
  (with-etcd (etcd config :on-leader #'become-leader :on-follower #'become-follower)
    (sleep 3)
    (get-etcd "hello" etcd)))

As this is a work-in-progress, details may change, and feedback is always welcome.

AG


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

2 Systems

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


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

2.1 cl-etcd

Author

Anthony Green <green@moxielogic.com>

License

AGPL3

Description

Run etcd as an asynchronous inferior process.

Version

0

Dependencies
Source

cl-etcd.asd (file)

Components

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

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 files   [Contents][Index]

3.1.1 cl-etcd.asd

Location

cl-etcd.asd

Systems

cl-etcd (system)


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

3.1.2 cl-etcd/package.lisp

Parent

cl-etcd (system)

Location

package.lisp

Packages

cl-etcd


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

3.1.3 cl-etcd/etcd.lisp

Dependency

package.lisp (file)

Parent

cl-etcd (system)

Location

etcd.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 cl-etcd

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: with-etcd (ETCD CONFIG &key ON-LEADER ON-FOLLOWER) &body BODY

Create an etcd subprocess, ETCD. CONFIG is a hashtable of etcd config options: name, initial-advertise-peer-urls, listen-peer-urls, listen-client-urls, advertise-client-urls, initial-cluster, initial-cluster-state, initial-cluster-token. Otherwise, CONFIG is nil and we are creating a non-clustered etcd instance.

Package

cl-etcd

Source

etcd.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: delete-dir-etcd DIR ETCD &key ERROR-ON-MISSING

Delete the directory DIR recursively from ETCD.

Package

cl-etcd

Source

etcd.lisp (file)

Function: delete-etcd KEY ETCD &key ERROR-ON-MISSING

Delete the KEY from ETCD.

Package

cl-etcd

Source

etcd.lisp (file)

Function: get-etcd KEY ETCD

Get the value of KEY from ETCD. Returns NIL if KEY not found. Throws an error on unexpected errors.

Package

cl-etcd

Source

etcd.lisp (file)

Writer

(setf get-etcd) (function)

Function: (setf get-etcd) VALUE KEY ETCD

Put the KEY/VALUE pair into ETCD.

Package

cl-etcd

Source

etcd.lisp (file)

Reader

get-etcd (function)

Function: watch-etcd ETCD KEY

Like GET-ETCD, but waits until value changes.

Package

cl-etcd

Source

etcd.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Generic functions

Generic Function: id OBJECT
Package

cl-etcd

Methods
Method: id (ETCD etcd)

automatically generated reader method

Source

etcd.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Classes

Class: etcd ()
Package

cl-etcd

Source

etcd.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: config
Initargs

:config

Readers

config (generic function)

Slot: process
Readers

process (generic function)

Slot: get-put-uri
Readers

get-put-uri (generic function)

Slot: id
Readers

id (generic function)

Slot: on-leader
Initargs

:on-leader

Readers

on-leader (generic function)

Slot: on-follower
Initargs

:on-follower

Readers

on-follower (generic function)

Slot: ready
Readers

ready (generic function)

Slot: version
Readers

version (generic function)

Slot: start-semaphore
Initform

(bordeaux-threads:make-semaphore)

Readers

start-semaphore (generic function)

Slot: role
Readers

role (generic function)


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: +became-regex+
Package

cl-etcd

Source

etcd.lisp (file)

Special Variable: +etcd-member-id-regex+
Package

cl-etcd

Source

etcd.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: %get-etcd KEY ETCD WAIT

Get the value of KEY from ETCD, but wait for a change first if WAIT. Returns NIL if KEY not found. Throws an error on unexpected errors.

Package

cl-etcd

Source

etcd.lisp (file)

Function: delete-process PROCESS
Package

cl-etcd

Source

etcd.lisp (file)

Function: get-process-output-string PROCESS
Package

cl-etcd

Source

etcd.lisp (file)

Function: monitor-etcd-output ETCD S
Package

cl-etcd

Source

etcd.lisp (file)

Function: process-send-input PROCESS STRING
Package

cl-etcd

Source

etcd.lisp (file)

Function: run-process COMMAND &key NAME OUTPUT-CALLBACK OUTPUT-CALLBACK-TYPE DIRECTORY
Package

cl-etcd

Source

etcd.lisp (file)

Function: write-to-buffer PROCESS STRING
Package

cl-etcd

Source

etcd.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Generic functions

Generic Function: config OBJECT
Package

cl-etcd

Methods
Method: config (ETCD etcd)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: get-put-uri OBJECT
Package

cl-etcd

Methods
Method: get-put-uri (ETCD etcd)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: on-follower OBJECT
Package

cl-etcd

Methods
Method: on-follower (ETCD etcd)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: on-leader OBJECT
Package

cl-etcd

Methods
Method: on-leader (ETCD etcd)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: process OBJECT
Package

cl-etcd

Methods
Method: process (ETCD etcd)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: process-buffer-stream OBJECT
Package

cl-etcd

Methods
Method: process-buffer-stream (PROCESS process)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: process-command OBJECT
Package

cl-etcd

Methods
Method: process-command (PROCESS process)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: process-name OBJECT
Package

cl-etcd

Methods
Method: process-name (PROCESS process)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: process-output-callback OBJECT
Package

cl-etcd

Methods
Method: process-output-callback (PROCESS process)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: process-output-callback-type OBJECT
Package

cl-etcd

Methods
Method: process-output-callback-type (PROCESS process)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: process-pointer OBJECT
Package

cl-etcd

Methods
Method: process-pointer (PROCESS process)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: process-read-thread OBJECT
Package

cl-etcd

Methods
Method: process-read-thread (PROCESS process)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: ready OBJECT
Package

cl-etcd

Methods
Method: ready (ETCD etcd)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: role OBJECT
Package

cl-etcd

Methods
Method: role (ETCD etcd)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: set-process-read-thread NEW-VALUE OBJECT
Package

cl-etcd

Methods
Method: set-process-read-thread NEW-VALUE (PROCESS process)

automatically generated writer method

Source

etcd.lisp (file)

Generic Function: start-semaphore OBJECT
Package

cl-etcd

Methods
Method: start-semaphore (ETCD etcd)

automatically generated reader method

Source

etcd.lisp (file)

Generic Function: version OBJECT
Package

cl-etcd

Methods
Method: version (ETCD etcd)

automatically generated reader method

Source

etcd.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Classes

Class: process ()
Package

cl-etcd

Source

etcd.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: pointer
Initargs

:pointer

Readers

process-pointer (generic function)

Slot: name
Initargs

:name

Readers

process-name (generic function)

Slot: command
Initargs

:command

Readers

process-command (generic function)

Slot: buffer-stream
Initargs

:buffer-stream

Readers

process-buffer-stream (generic function)

Slot: read-thread
Initargs

:read-thread

Readers

process-read-thread (generic function)

Writers

set-process-read-thread (generic function)

Slot: output-callback
Initargs

:output-callback

Readers

process-output-callback (generic function)

Slot: callback-type
Initargs

:output-callback-type

Readers

process-output-callback-type (generic function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-etcd.asd: The cl-etcd․asd file
cl-etcd/etcd.lisp: The cl-etcd/etcd․lisp file
cl-etcd/package.lisp: The cl-etcd/package․lisp file

F
File, Lisp, cl-etcd.asd: The cl-etcd․asd file
File, Lisp, cl-etcd/etcd.lisp: The cl-etcd/etcd․lisp file
File, Lisp, cl-etcd/package.lisp: The cl-etcd/package․lisp file

L
Lisp File, cl-etcd.asd: The cl-etcd․asd file
Lisp File, cl-etcd/etcd.lisp: The cl-etcd/etcd․lisp file
Lisp File, cl-etcd/package.lisp: The cl-etcd/package․lisp file

Jump to:   C   F   L  

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

A.2 Functions

Jump to:   %   (  
C   D   F   G   I   M   O   P   R   S   V   W  
Index Entry  Section

%
%get-etcd: Internal functions

(
(setf get-etcd): Exported functions

C
config: Internal generic functions
config: Internal generic functions

D
delete-dir-etcd: Exported functions
delete-etcd: Exported functions
delete-process: Internal functions

F
Function, %get-etcd: Internal functions
Function, (setf get-etcd): Exported functions
Function, delete-dir-etcd: Exported functions
Function, delete-etcd: Exported functions
Function, delete-process: Internal functions
Function, get-etcd: Exported functions
Function, get-process-output-string: Internal functions
Function, monitor-etcd-output: Internal functions
Function, process-send-input: Internal functions
Function, run-process: Internal functions
Function, watch-etcd: Exported functions
Function, write-to-buffer: Internal functions

G
Generic Function, config: Internal generic functions
Generic Function, get-put-uri: Internal generic functions
Generic Function, id: Exported generic functions
Generic Function, on-follower: Internal generic functions
Generic Function, on-leader: Internal generic functions
Generic Function, process: Internal generic functions
Generic Function, process-buffer-stream: Internal generic functions
Generic Function, process-command: Internal generic functions
Generic Function, process-name: Internal generic functions
Generic Function, process-output-callback: Internal generic functions
Generic Function, process-output-callback-type: Internal generic functions
Generic Function, process-pointer: Internal generic functions
Generic Function, process-read-thread: Internal generic functions
Generic Function, ready: Internal generic functions
Generic Function, role: Internal generic functions
Generic Function, set-process-read-thread: Internal generic functions
Generic Function, start-semaphore: Internal generic functions
Generic Function, version: Internal generic functions
get-etcd: Exported functions
get-process-output-string: Internal functions
get-put-uri: Internal generic functions
get-put-uri: Internal generic functions

I
id: Exported generic functions
id: Exported generic functions

M
Macro, with-etcd: Exported macros
Method, config: Internal generic functions
Method, get-put-uri: Internal generic functions
Method, id: Exported generic functions
Method, on-follower: Internal generic functions
Method, on-leader: Internal generic functions
Method, process: Internal generic functions
Method, process-buffer-stream: Internal generic functions
Method, process-command: Internal generic functions
Method, process-name: Internal generic functions
Method, process-output-callback: Internal generic functions
Method, process-output-callback-type: Internal generic functions
Method, process-pointer: Internal generic functions
Method, process-read-thread: Internal generic functions
Method, ready: Internal generic functions
Method, role: Internal generic functions
Method, set-process-read-thread: Internal generic functions
Method, start-semaphore: Internal generic functions
Method, version: Internal generic functions
monitor-etcd-output: Internal functions

O
on-follower: Internal generic functions
on-follower: Internal generic functions
on-leader: Internal generic functions
on-leader: Internal generic functions

P
process: Internal generic functions
process: Internal generic functions
process-buffer-stream: Internal generic functions
process-buffer-stream: Internal generic functions
process-command: Internal generic functions
process-command: Internal generic functions
process-name: Internal generic functions
process-name: Internal generic functions
process-output-callback: Internal generic functions
process-output-callback: Internal generic functions
process-output-callback-type: Internal generic functions
process-output-callback-type: Internal generic functions
process-pointer: Internal generic functions
process-pointer: Internal generic functions
process-read-thread: Internal generic functions
process-read-thread: Internal generic functions
process-send-input: Internal functions

R
ready: Internal generic functions
ready: Internal generic functions
role: Internal generic functions
role: Internal generic functions
run-process: Internal functions

S
set-process-read-thread: Internal generic functions
set-process-read-thread: Internal generic functions
start-semaphore: Internal generic functions
start-semaphore: Internal generic functions

V
version: Internal generic functions
version: Internal generic functions

W
watch-etcd: Exported functions
with-etcd: Exported macros
write-to-buffer: Internal functions

Jump to:   %   (  
C   D   F   G   I   M   O   P   R   S   V   W  

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

A.3 Variables

Jump to:   +  
B   C   G   I   N   O   P   R   S   V  
Index Entry  Section

+
+became-regex+: Internal special variables
+etcd-member-id-regex+: Internal special variables

B
buffer-stream: Internal classes

C
callback-type: Internal classes
command: Internal classes
config: Exported classes

G
get-put-uri: Exported classes

I
id: Exported classes

N
name: Internal classes

O
on-follower: Exported classes
on-leader: Exported classes
output-callback: Internal classes

P
pointer: Internal classes
process: Exported classes

R
read-thread: Internal classes
ready: Exported classes
role: Exported classes

S
Slot, buffer-stream: Internal classes
Slot, callback-type: Internal classes
Slot, command: Internal classes
Slot, config: Exported classes
Slot, get-put-uri: Exported classes
Slot, id: Exported classes
Slot, name: Internal classes
Slot, on-follower: Exported classes
Slot, on-leader: Exported classes
Slot, output-callback: Internal classes
Slot, pointer: Internal classes
Slot, process: Exported classes
Slot, read-thread: Internal classes
Slot, ready: Exported classes
Slot, role: Exported classes
Slot, start-semaphore: Exported classes
Slot, version: Exported classes
Special Variable, +became-regex+: Internal special variables
Special Variable, +etcd-member-id-regex+: Internal special variables
start-semaphore: Exported classes

V
version: Exported classes

Jump to:   +  
B   C   G   I   N   O   P   R   S   V  

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

A.4 Data types

Jump to:   C   E   P   S  
Index Entry  Section

C
cl-etcd: The cl-etcd system
cl-etcd: The cl-etcd package
Class, etcd: Exported classes
Class, process: Internal classes

E
etcd: Exported classes

P
Package, cl-etcd: The cl-etcd package
process: Internal classes

S
System, cl-etcd: The cl-etcd system

Jump to:   C   E   P   S