Skip to content

Commit

Permalink
Doc review fixes (#153)
Browse files Browse the repository at this point in the history 
Fix multiple issues found during the full doc review #91.

Fixes #120, fixes #121, fixes #122, fixes #124, fixes #125, fixes #126,
fixes #127, fixes #128, fixes #130, fixes #131, fixes #132, fixes #133,
fixes #134, fixes #135, fixes #136, fixes #137, fixes #138, fixes #139,
fixes #140, fixes #141.

---------

Signed-off-by: Viktor Söderqvist <[email protected]>
  • Loading branch information
@zuiderkwast
zuiderkwast authored Jul 3, 2024
1 parent dcee122 commit 1cba52c
Show file tree
Hide file tree
Showing 23 changed files with 745 additions and 682 deletions.
2 changes: 1 addition & 1 deletion commands/command-count.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Returns @integer-reply of number of total commands in this Valkey server.
Returns the total number of commands in this Valkey server.

## Examples

Expand Down
7 changes: 1 addition & 6 deletions topics/benchmark.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -325,12 +325,7 @@ world scenarios, Valkey throughput is limited by the network well before being
limited by the CPU. To consolidate several high-throughput Valkey instances
on a single server, it worth considering putting a 10 Gbit/s NIC
or multiple 1 Gbit/s NICs with TCP/IP bonding.
+ CPU is another very important factor. Being single-threaded, Valkey favors
fast CPUs with large caches and not many cores. At this game, Intel CPUs are
currently the winners. It is not uncommon to get only half the performance on
an AMD Opteron CPU compared to similar Nehalem EP/Westmere EP/Sandy Bridge
Intel CPUs with Valkey. When client and server run on the same box, the CPU is
the limiting factor with valkey-benchmark.
+ CPU is another important factor.
+ Speed of RAM and memory bandwidth seem less critical for global performance
especially for small objects. For large objects (>10 KB), it may become
noticeable though. Usually, it is not really cost-effective to buy expensive
Expand Down
4 changes: 1 addition & 3 deletions topics/cluster-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,6 @@ Valkey Cluster is a distributed implementation of Valkey with the following goal
* Acceptable degree of write safety: the system tries (in a best-effort way) to retain all the writes originating from clients connected with the majority of the master nodes. Usually there are small windows where acknowledged writes can be lost. Windows to lose acknowledged writes are larger when clients are in a minority partition.
* Availability: Valkey Cluster is able to survive partitions where the majority of the master nodes are reachable and there is at least one reachable replica for every master node that is no longer reachable. Moreover using *replicas migration*, masters no longer replicated by any replica will receive one from a master which is covered by multiple replicas.

What is described in this document is implemented in Redis OSS 3.0 or greater.

### Implemented subset

Valkey Cluster implements all the single key commands available in the
Expand Down Expand Up @@ -1206,7 +1204,7 @@ The cluster makes sure the published shard messages are forwarded to all nodes i

/*
* Copyright 2001-2010 Georges Menie (www.menie.org)
* Copyright 2010 Salvatore Sanfilippo (adapted to Valkey coding style)
* Copyright 2010 Salvatore Sanfilippo (adapted to Redis coding style)
* All rights reserved.
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
Expand Down
84 changes: 42 additions & 42 deletions topics/cluster-tutorial.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -325,16 +325,16 @@ You can also test your Valkey Cluster using the `valkey-cli` command line utilit

```
$ valkey-cli -c -p 7000
valkey 127.0.0.1:7000> set foo bar
127.0.0.1:7000> set foo bar
-> Redirected to slot [12182] located at 127.0.0.1:7002
OK
valkey 127.0.0.1:7002> set hello world
127.0.0.1:7002> set hello world
-> Redirected to slot [866] located at 127.0.0.1:7000
OK
valkey 127.0.0.1:7000> get foo
127.0.0.1:7000> get foo
-> Redirected to slot [12182] located at 127.0.0.1:7002
"bar"
valkey 127.0.0.1:7002> get hello
127.0.0.1:7002> get hello
-> Redirected to slot [866] located at 127.0.0.1:7000
"world"
```
Expand Down Expand Up @@ -370,44 +370,44 @@ The first is the following, and is the
[`example.rb`](https://github.com/antirez/redis-rb-cluster/blob/master/example.rb)
file inside the redis-rb-cluster distribution:

```
1 require './cluster'
2
3 if ARGV.length != 2
4 startup_nodes = [
5 {:host => "127.0.0.1", :port => 7000},
6 {:host => "127.0.0.1", :port => 7001}
7 ]
8 else
9 startup_nodes = [
10 {:host => ARGV[0], :port => ARGV[1].to_i}
11 ]
12 end
13
14 rc = RedisCluster.new(startup_nodes,32,:timeout => 0.1)
15
16 last = false
17
18 while not last
19 begin
20 last = rc.get("__last__")
21 last = 0 if !last
22 rescue => e
23 puts "error #{e.to_s}"
24 sleep 1
25 end
26 end
27
28 ((last.to_i+1)..1000000000).each{|x|
29 begin
30 rc.set("foo#{x}",x)
31 puts rc.get("foo#{x}")
32 rc.set("__last__",x)
33 rescue => e
34 puts "error #{e.to_s}"
35 end
36 sleep 0.1
37 }
```ruby
require './cluster'

if ARGV.length != 2
startup_nodes = [
{:host => "127.0.0.1", :port => 7000},
{:host => "127.0.0.1", :port => 7001}
]
else
startup_nodes = [
{:host => ARGV[0], :port => ARGV[1].to_i}
]
end

rc = RedisCluster.new(startup_nodes,32,:timeout => 0.1)

last = false

while not last
begin
last = rc.get("__last__")
last = 0 if !last
rescue => e
puts "error #{e.to_s}"
sleep 1
end
end

((last.to_i+1)..1000000000).each{|x|
begin
rc.set("foo#{x}",x)
puts rc.get("foo#{x}")
rc.set("__last__",x)
rescue => e
puts "error #{e.to_s}"
end
sleep 0.1
}
```

The application does a very simple thing, it sets keys in the form `foo<number>` to `number`, one after the other. So if you run the program the result is the
Expand Down
2 changes: 1 addition & 1 deletion topics/eval-intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ The following attempts to demonstrate the distribution of input arguments betwee
```

**Note:**
as can been seen above, Lua's table arrays are returned as [RESP2 array replies](protocol.md#resp-arrays), so it is likely that your client's library will convert it to the native array data type in your programming language.
as can been seen above, Lua's table arrays are returned as [RESP2 array replies](protocol.md#arrays), so it is likely that your client's library will convert it to the native array data type in your programming language.
Please refer to the rules that govern [data type conversion](lua-api.md#data-type-conversion) for more pertinent information.

## Interacting with Valkey from a script
Expand Down
62 changes: 31 additions & 31 deletions topics/lua-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,7 @@ Evaluating this script with more than one argument will return:
* Available in scripts: yes
* Available in functions: yes

This is a helper function that returns an [error reply](protocol.md#resp-errors).
This is a helper function that returns an [error reply](protocol.md#simply-errors).
The helper accepts a single string argument and returns a Lua table with the _err_ field set to that string.

The outcome of the following code is that _error1_ and _error2_ are identical for all intents and purposes:
Expand Down Expand Up @@ -211,7 +211,7 @@ Scripts are advised to follow this convention, as shown in the example above, bu
* Available in scripts: yes
* Available in functions: yes

This is a helper function that returns a [simple string reply](protocol.md#resp-simple-strings).
This is a helper function that returns a [simple string reply](protocol.md#simple-strings).
"OK" is an example of a standard Valkey status reply.
The Lua API represents status replies as tables with a single field, _ok_, set with a simple status string.

Expand Down Expand Up @@ -547,27 +547,27 @@ The following sections describe the type conversion rules between Lua and Valkey

The following type conversion rules apply to the execution's context by default as well as after calling `server.setresp(2)`:

* [RESP2 integer reply](protocol.md#resp-integers) -> Lua number
* [RESP2 bulk string reply](protocol.md#resp-bulk-strings) -> Lua string
* [RESP2 array reply](protocol.md#resp-arrays) -> Lua table (may have other Valkey data types nested)
* [RESP2 status reply](protocol.md#resp-simple-strings) -> Lua table with a single _ok_ field containing the status string
* [RESP2 error reply](protocol.md#resp-errors) -> Lua table with a single _err_ field containing the error string
* [RESP2 null bulk reply](protocol.md#null-elements-in-arrays) and [null multi bulk reply](protocol.md#resp-arrays) -> Lua false boolean type
* [RESP2 integer reply](protocol.md#integers) -> Lua number
* [RESP2 bulk string reply](protocol.md#bulk-strings) -> Lua string
* [RESP2 array reply](protocol.md#arrays) -> Lua table (may have other Valkey data types nested)
* [RESP2 status reply](protocol.md#simple-strings) -> Lua table with a single _ok_ field containing the status string
* [RESP2 error reply](protocol.md#simple-errors) -> Lua table with a single _err_ field containing the error string
* [RESP2 null bulk reply and null multi bulk reply](protocol.md#nulls) -> Lua false boolean type

## Lua to RESP2 type conversion

The following type conversion rules apply by default as well as after the user had called `HELLO 2`:

* Lua number -> [RESP2 integer reply](protocol.md#resp-integers) (the number is converted into an integer)
* Lua string -> [RESP bulk string reply](protocol.md#resp-bulk-strings)
* Lua table (indexed, non-associative array) -> [RESP2 array reply](protocol.md#resp-arrays) (truncated at the first Lua `nil` value encountered in the table, if any)
* Lua table with a single _ok_ field -> [RESP2 status reply](protocol.md#resp-simple-strings)
* Lua table with a single _err_ field -> [RESP2 error reply](protocol.md#resp-errors)
* Lua boolean false -> [RESP2 null bulk reply](protocol.md#null-elements-in-arrays)
* Lua number -> [RESP2 integer reply](protocol.md#integers) (the number is converted into an integer)
* Lua string -> [RESP bulk string reply](protocol.md#bulk-strings)
* Lua table (indexed, non-associative array) -> [RESP2 array reply](protocol.md#arrays) (truncated at the first Lua `nil` value encountered in the table, if any)
* Lua table with a single _ok_ field -> [RESP2 status reply](protocol.md#simple-strings)
* Lua table with a single _err_ field -> [RESP2 error reply](protocol.md#simple-errors)
* Lua boolean false -> [RESP2 null bulk reply](protocol.md#nulls)

There is an additional Lua-to-Valkey conversion rule that has no corresponding Valkey-to-Lua conversion rule:

* Lua Boolean `true` -> [RESP2 integer reply](protocol.md#resp-integers) with value of 1.
* Lua Boolean `true` -> [RESP2 integer reply](protocol.md#integers) with value of 1.

There are three additional rules to note about converting Lua to Valkey data types:

Expand Down Expand Up @@ -613,36 +613,36 @@ As you can see, the float value of _3.333_ gets converted to an integer _3_, the

### RESP3 to Lua type conversion

[RESP3](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md) is a newer version of the [Valkey Serialization Protocol](protocol.md).
It is available as an opt-in choice as of Redis OSS v6.0.
RESP3 is a newer version of Valkey's [Serialization Protocol](protocol.md).
It is available as an opt-in choice.

An executing script may call the [`server.setresp`](#server.setresp) function during its execution and switch the protocol version that's used for returning replies from Valkey' commands (that can be invoked via [`server.call()`](#server.call) or [`server.pcall()`](#server.pcall)).

Once Valkey' replies are in RESP3 protocol, all of the [RESP2 to Lua conversion](#resp2-to-lua-type-conversion) rules apply, with the following additions:

* [RESP3 map reply](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#map-type) -> Lua table with a single _map_ field containing a Lua table representing the fields and values of the map.
* [RESP set reply](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#set-reply) -> Lua table with a single _set_ field containing a Lua table representing the elements of the set as fields, each with the Lua Boolean value of `true`.
* [RESP3 null](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#null-reply) -> Lua `nil`.
* [RESP3 true reply](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#boolean-reply) -> Lua true boolean value.
* [RESP3 false reply](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#boolean-reply) -> Lua false boolean value.
* [RESP3 double reply](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#double-type) -> Lua table with a single _double_ field containing a Lua number representing the double value.
* [RESP3 big number reply](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#big-number-type) -> Lua table with a single _big_number_ field containing a Lua string representing the big number value.
* [Valkey verbatim string reply](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#verbatim-string-type) -> Lua table with a single _verbatim_string_ field containing a Lua table with two fields, _string_ and _format_, representing the verbatim string and its format, respectively.
* [Map reply](protocol.md#maps) -> Lua table with a single _map_ field containing a Lua table representing the fields and values of the map.
* [Set reply](protocol.md#sets) -> Lua table with a single _set_ field containing a Lua table representing the elements of the set as fields, each with the Lua Boolean value of `true`.
* [Null](protocol.md#nulls) -> Lua `nil`.
* [True reply](protocol.md#booleans) -> Lua true boolean value.
* [False reply](protocol.md#booleans) -> Lua false boolean value.
* [Double reply](protocol.md#doubles) -> Lua table with a single _double_ field containing a Lua number representing the double value.
* [Big number reply](protocol.md#big-numbers) -> Lua table with a single _big_number_ field containing a Lua string representing the big number value.
* [Verbatim string reply](protocol.md#verbatim-strings) -> Lua table with a single _verbatim_string_ field containing a Lua table with two fields, _string_ and _format_, representing the verbatim string and its format, respectively.

**Note:**
the RESP3 [big number](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#big-number-type) and [verbatim strings](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#verbatim-string-type) replies are only supported as of Redis OSS v7.0 and greater.
the RESP3 [big number](protocol.md#big-numbers) and [verbatim strings](protocol.md#verbatim-strings) replies are supported since Redis OSS 7.0.
Also, presently, RESP3's [attributes](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#attribute-type), [streamed strings](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#streamed-strings) and [streamed aggregate data types](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#streamed-aggregate-data-types) are not supported by the Valkey Lua API.

### Lua to RESP3 type conversion

Regardless of the script's choice of protocol version set for replies with the [`server.setresp()` function] when it calls `server.call()` or `server.pcall()`, the user may opt-in to using RESP3 (with the `HELLO 3` command) for the connection.
Although the default protocol for incoming client connections is RESP2, the script should honor the user's preference and return adequately-typed RESP3 replies, so the following rules apply on top of those specified in the [Lua to RESP2 type conversion](#lua-to-resp2-type-conversion) section when that is the case.

* Lua Boolean -> [RESP3 Boolean reply](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#boolean-reply) (note that this is a change compared to the RESP2, in which returning a Boolean Lua `true` returned the number 1 to the Valkey client, and returning a `false` used to return a `null`.
* Lua table with a single _map_ field set to an associative Lua table -> [RESP3 map reply](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#map-type).
* Lua table with a single _set_ field set to an associative Lua table -> [RESP3 set reply](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#set-type). Values can be set to anything and are discarded anyway.
* Lua table with a single _double_ field to an associative Lua table -> [RESP3 double reply](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#double-type).
* Lua nil -> [RESP3 null](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#null-reply).
* Lua Boolean -> [RESP3 Boolean reply](protocol.md#booleans) (note that this is a change compared to the RESP2, in which returning a Boolean Lua `true` returned the number 1 to the Valkey client, and returning a `false` used to return a `null`.
* Lua table with a single _map_ field set to an associative Lua table -> [RESP3 map reply](protocol.md#maps).
* Lua table with a single _set_ field set to an associative Lua table -> [RESP3 set reply](protocol.md#sets). Values can be set to anything and are discarded anyway.
* Lua table with a single _double_ field to an associative Lua table -> [RESP3 double reply](protocol.md#doubles).
* Lua nil -> [RESP3 null](protocol.md#nulls).

However, if the connection is set use the RESP2 protocol, and even if the script replies with RESP3-typed responses, Valkey will automatically perform a RESP3 to RESP2 conversion of the reply as is the case for regular commands.
That means, for example, that returning the RESP3 map type to a RESP2 connection will result in the reply being converted to a flat RESP2 array that consists of alternating field names and their values, rather than a RESP3 map.
Expand Down
Loading

0 comments on commit 1cba52c

Please sign in to comment.