Skip to content

Commit 1a5011c

Browse files
markumanmarkuman
committed
documentation in mdbook
1 parent 9b68aaa commit 1a5011c

27 files changed

+593
-0
lines changed

‎docs/book.toml

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[book]
2+
authors = ["Markus Bergholz"]
3+
multilingual = false
4+
src = "src"
5+
title = "GNU Octave Redis Client"
6+

‎docs/src/SUMMARY.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Summary
2+
3+
- [go-redis](./goredis.md)
4+
- [Build](./build.md)
5+
- [Limitations](./limitations.md)
6+
- [About](./about/summary.md)
7+
- [Data Structure](./about/datastructure.md)
8+
- [Collaborative Workspace](./about/collaborativeworkspace.md)
9+
- [Gaussian Elimination](./about/gaussianelimination.md)
10+
- [Array Reply](./about/arrayreply.md)
11+
- [Call](./about/call.md)
12+
- [Usage](./usage/summary.md)
13+
- [Basics](./usage/basics.md)
14+
- [set, get, getset, append](./usage/setget.md)
15+
- [incr, decr](./usage/incrdecr.md)
16+
- [del](./usage/del.md)
17+
- [move](./usage/move.md)
18+
- [db](./usage/db.md)
19+
- [rename](./usage/rename.md)
20+
- [save](./usage/save.md)
21+
- [type](./usage/type.md)
22+
- [Cluster](./cluster.md)
23+
- [Pipeline](./pipeline.md)
24+
- [Matlab / GNU Octave special](./octave.md)

‎docs/src/about/arrayreply.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
### array reply
2+
An array reply will be transformed into a cell array in Octave/Matlab.
3+
4+
octave:2> r.call('keys *')
5+
ans =
6+
{
7+
[1,1] = b
8+
[2,1] = A
9+
}

‎docs/src/about/call.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
### CALL
2+
`r.call(command)`
3+
4+
* for debugging
5+
* functions that are not directly supported by redis() class
6+
* for disable the overhead of redis() class functions
7+
* command can be a string or a cell (e.g. `{'SET', 'my keyname', 'this is a value'}`)

‎docs/src/about/collaborativeworkspace.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Collaborative Workspace
2+
3+
You can use `go-redis` as a collaborative workspace for GNU Octave and Matlab.
4+
5+
# Write your (interim) results in GNU Octave or Matlab
6+
7+
>> m = rand(10,10,10,10,10);
8+
>> numel(m)
9+
10+
ans =
11+
12+
100000
13+
14+
>> r = redis;
15+
>> r.precision = 16;
16+
>> tic, r.array2redis(m); toc
17+
Elapsed time is 0.206611 seconds.
18+
>> r.call('keys m*')
19+
20+
ans =
21+
22+
'm'
23+
'm.dimension'
24+
'm.values'
25+
26+
>> sum(sum(sum(sum(sum(m)))))
27+
28+
ans =
29+
30+
50197.9709091746
31+
32+
>>
33+
34+
35+
# Read your (interim) results in GNU Octave or Matlab
36+
37+
octave:1> r = redis;
38+
octave:2> tic, m = r.redis2array('m'); toc
39+
Elapsed time is 0.360481 seconds.
40+
octave:3> sum(sum(sum(sum(sum(m)))))
41+
ans = 50197.9709091746
42+
octave:4>

‎docs/src/about/datastructure.md

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Data Structure
2+
3+
In this page I try to explain the principles of the datastructure which is created in `redis` by `go-redis`.
4+
5+
6+
## Strings
7+
8+
Strings can be easily stored and read with `SET` and `GET`.
9+
10+
>> r.set('string', 'hello_github')
11+
12+
ans =
13+
14+
OK
15+
...
16+
127.0.0.1:6379> get string
17+
"hello_github"
18+
19+
>> r.set('string', 'hello github');
20+
>> r.get('string');
21+
22+
hello github
23+
24+
25+
26+
## Arrays
27+
28+
When you're using `array2redis`, two lists using `RPUSH` will be created.
29+
30+
31+
The first list will be `keyname.values`.
32+
The values are stored _(like in the nature of GNU Octave and Matlab)_ in one column. It's simple [Column Major Order](https://en.wikipedia.org/wiki/Row-major_order).
33+
34+
The second list is `keyname.dimension`.
35+
This is where the information of `size(array)` is stored. _(column major order too)_.
36+
37+
At least, `keyname` is the group of `keyname.values` and `keyname.dimension` using `SADD`.
38+
39+
You can save any numerical array (size and number of dimensions doesn't matter). The only limitting factor might be your bandwidth to redis and the max memory size of your redis instance.
40+
41+
With `redis2array` you can read back the array to Matlab/Octave.
42+
43+
When you've just need a range of your array, you can simply use `range2array`. But take care, it only support 2D and 3D arrays!
44+
45+
```mermaid
46+
graph TB
47+
elb-->varnish
48+
subgraph lekker-web-container
49+
varnish["varnish Port 80"]-->apache2["apache2 Port 8080"]
50+
apache2-->php_sulu
51+
end
52+
php_sulu-->rds
53+
php_sulu-->efs
54+
```

‎docs/src/about/gaussianelimination.md

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Gaussian Elimination
2+
3+
### load script permanent into redis
4+
5+
>> r = r.loadGaussian('go-redis/mex/gaussian.lua');
6+
7+
### general workflow in GNU Octave/Matlab
8+
9+
To solve A*x = b, let's create A and b.
10+
11+
>> r = redis; % initialize
12+
>> a = rand(10,10); % create a 10x10 random matrix
13+
>> b = (1:10)'; % create b
14+
>> r.array2redis(a); % save a in redis
15+
>> r.array2redis(b); % save b in redis
16+
17+
### calculate gaussian elimination
18+
19+
... the calculation is made by lua inside of redis.
20+
21+
>> tic, x = r.gaussian('a','b'); toc
22+
Elapsed time is 0.019226 seconds.
23+
24+
25+
### compare the result
26+
27+
Result calculated by GNU Octave/Matlab
28+
29+
>> a\b
30+
31+
ans =
32+
33+
2.9227
34+
11.7630
35+
-20.2694
36+
16.8191
37+
3.1782
38+
2.1669
39+
7.7981
40+
-5.2681
41+
-19.7751
42+
22.5863
43+
44+
Result calculated by Lua in Redis
45+
46+
47+
48+
>> x
49+
50+
x =
51+
52+
2.9227
53+
11.7630
54+
-20.2694
55+
16.8191
56+
3.1782
57+
2.1669
58+
7.7981
59+
-5.2681
60+
-19.7751
61+
22.5863
62+
63+
...if you get rounding problems, increase `r.precision` before storing the arrays.
64+
65+
### why?
66+
67+
Ever run out of memory in GNU Octave or Matlab? Well,
68+
- simple pump your huge matrices into a redis instance on a larger server.
69+
- pray for fast bandwidth
70+
- worry about visualization or varification methodes of those data
71+
72+

‎docs/src/about/summary.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# About go-redis
2+
3+
Discover internals and possibilities...
4+
5+
- [Data Structure](./datastructure.md)
6+
- [Collaborative Workspace](./collaborativeworkspace.md)
7+
- [Gaussian Elimination](./gaussianelimination.md)
8+
- [Array Reply](./arrayreply.md)
9+
- [Call](./call.md)

‎docs/src/build.md

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Requirements
2+
3+
* Classdef support
4+
* Octave >= 4.0
5+
* Matlab >= R2012b? _(dunno when classdef was introduced...)_
6+
* C-Compiler
7+
* [hiredis library](https://github.com/redis/hiredis/)
8+
* Linux or Mac OS X _(never tried with Windows)_
9+
10+
11+
# Build instructions
12+
13+
1. install a C compiler
14+
* Ubuntu: `sudo apt-get install build-essential`
15+
* Arch: `sudo pacman -S base-devel`
16+
* Mac: Install xcode
17+
2. install [hiredis library](https://github.com/redis/hiredis/)
18+
* Ubuntu: `sudo apt-get install libhiredis-dev libhiredis0.10` _*for 14.04 LTS_
19+
* Arch: `sudo pacman -S hiredis`
20+
* Mac: `brew install hiredis`
21+
3. mex.h
22+
* Distributed with your Matlab or GNU Octave installation
23+
4. clone/download and build go-redis directly from Matlab/GNU Octave
24+
25+
>> cd go-redis/mex
26+
>> setup
27+
>> % go where ever you want and just do "addpath ('go-redis/inst')"
28+
29+
The default path to hiredis is set to `/usr/include/hiredis`. You can change it by set a variable `LIBPATH` with a absolute path to hiredis before running the setup script.
30+
31+
5. optional - run tests
32+
33+
The `mex` folder contains a `test_redis.m` script with many `assert()` checks.
34+
35+
>> test_redis
36+
This test will delete all databases of your redis instance on 127.0.0.1 6379.
37+
To continue type "YES": YES
38+
39+
everything passed
40+
>>
41+
42+
43+
### Manually Matlab Instruction
44+
45+
You can compile it directly in the Matlab commandline.
46+
47+
mex -lhiredis -I/usr/include/hiredis/ CFLAGS='-fPIC -O2 -pedantic -std=c++11 -g' redis_.cpp
48+
49+
Afterwards mv `redis_.mex*` from `mex` folder into `inst/private` folder.
50+
51+
### Manually GNU Octave Instruction
52+
53+
From GNU Octave commandline
54+
55+
mkoctfile -lhiredis -I/usr/include/hiredis --mex -fPIC -O2 -pedantic -std=c++11 -g redis_.cpp
56+
57+
Afterwards mv `redis_.mex` from `mex` folder into `inst/private` folder.
58+
59+
**Currently (3/19/2015) there is a bug in classdef. You have to do `addpath private` in octave as a workaround!**
60+
https://savannah.gnu.org/bugs/?41723
61+
62+
### Manually Bash Instruction
63+
64+
You can compile it in bash too
65+
66+
gcc -fPIC -I <PATH TO mex.h> -lm -I <PATH TO hiredis.h> -lhiredis -shared -O2 redis_.cpp -o redis_.mex
67+
68+
e.g.
69+
70+
gcc -fPIC -std=c++11 -I /usr/include/octave-4.0.0/octave/ -lm -I /usr/include/hiredis/ -lhiredis -shared -O2 -pedantic redis_.cpp -o redis_.mex

‎docs/src/cluster.md

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
### CLUSTER
2+
3+
`go-redis` support the redis-cluster automatically (when the redis instance is a cluster).
4+
5+
>> r = redis('127.0.0.1', 30001)
6+
7+
r =
8+
9+
redis with properties:
10+
11+
precision: 4
12+
batchsize: 64
13+
verboseCluster: 1
14+
15+
>> r.get('Z')
16+
MOVED 15295 127.0.0.1:30003
17+
18+
ans =
19+
20+
5
21+
22+
>> r.get('A')
23+
MOVED 6373 127.0.0.1:30002
24+
25+
ans =
26+
27+
4
28+
29+
>> r.verboseCluster = false;
30+
>> r.set('Z', 7)
31+
32+
ans =
33+
34+
OK
35+
36+
>> r.get('Z')
37+
38+
ans =
39+
40+
7

‎docs/src/collaborativeworkspace.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Collaborative Workspace

‎docs/src/datastructure.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Data Structure

‎docs/src/gaussianelimination.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Gaussian Elimination

‎docs/src/goredis.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# go-redis
2+
3+
[![pipeline status](https://gitlab.com/markuman/go-redis/badges/master/pipeline.svg)](https://gitlab.com/markuman/go-redis/commits/master)
4+
5+
* https://git.osuv.de/m/go-redis/
6+
* https://gitlab.com/markuman/go-redis/
7+
8+
go-redis - **G**NU **O**ctave **redis** client
9+
10+
...but Matlab is supported too. When I don't support Matlab, someone else will do and I have to emulate it with Octave.
11+
12+
Tested with Linux and Mac OS X.
13+
14+
For more detailed information next to this `README.md`, take a look at the Wiki

‎docs/src/limitations.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# limitations
2+
3+
* `pipeline()` can not handle cluster instances!
4+
5+
* GNU Octave
6+
* there is a bug in classdef. You have to do `addpath private` in octave as a workaround! https://savannah.gnu.org/bugs/?41723
7+
* `inputname` is currently not supported in a classdef environment. So you have to name you array by yourself when using `array2redis`.
8+
9+
10+
# todo
11+
12+
* maybe add `hiredis` as a submodule to simplify the setup process?
13+
* improve c-code
14+
* still some problems with unicodes between matlab and GNU Octave (it's a natural problem between octave and matlab)
15+
* improve `pipeline` (subclass)

0 commit comments

Comments
 (0)