19. DB access part 2: Redis

iFun Engine provides a RedisClient class to communicate with Redis servers. RedisClient provides a function to respond to Redis Commands.

The explanation below does not include all features and functions of RedisClient. For more details, please see RedisClient class.

Note

RedisClient was written based on Redis Server version 2.8.4.

19.1. Starting connections

19.1.1. Setting values

class RedisClient {
  static Ptr<RedisClient> Create(server_ip, server_port, auth_pass,
                                 connection_count [, invoke_as_event = true]);
};
public class RedisClient
{
  static public RedisClient Create (server_ip, server_port, auth_pass,
                                    connection_count [, invoke_as_event = true]);
}

Set values to start the initial connection.

server_ip Enter the Redis server’s IP. E.g. 127.0.0.1
server_port Enter the Redis server’s port. E.g. 6379
auth_pass Enter the auth pass set on the Redis server.
connection_count Enter the number of connections in the connection pool.
invoke_as_event Whether to handle callback functions sent to asynchronous functions is decided through Events. The default setting is true. If false, it is invoked in a separate thread.

Note

If there are more than 2 connections, they are executed in parallel, so the Redis command order is not guaranteed. If the sequence of Redis commands must be guaranteed, please refer to Asynchronous command order and tags.

Note

If executing a Redis Subscribe command, one connection from the connection pool is chosen to handle Subscribe and set to handle only Subscribe afterward. Therefore, if there is only one connection, a command like Get is not performed after the Subscribe command, but left in the internal queue. (Commands left in the queue after that are handled when unsubscribing.) In this case, there must be at least 2 connections.

19.1.2. Initializing the connection pool

class RedisClient {
  void Initialize();
};
public class RedisClient
{
  public void Start();
}

Reset the connection pool to match the number of connections input using Create(). You can execute Redis commands after invoking this function.

19.2. Executing commands

19.2.1. Supported commands

The currently supported Redis commands are as follows. Del, Exists and similar functions are asynchronous commands. Sync is added to the end of synchronous commands.

Details on each command can be found in Redis Commands.

Keys
Del, Exists, Expire, PExpire, Persist, TTL, PTTL, Rename
Strings
Append, Incr, IncrBy, IncrByFloat, Decr, DecrBy, StrLen, Get, MGet, GetRange, GetSet, Set, SetEx, PSetEx, SetNx, MSet, MSetNx, BitCount, BitOp, GetBit, SetBit
Hashes
HExists, HKeys, HVals, HLen, HIncrBy, HIncrByFloat, HDel, HGet, HGetAll, HMGet, HSet, HSetNx, HMSet
Lists
LLen, LIndex, LRange, LRem, LTrim, LPush, RPush, LPop, RPop, LInsert, LSet
Sets
SCard, SIsMember, SMembers, SRandMember, SDiff, SDiffStore, SInter, SInterStore, SUnion, SUnionStore, SAdd, SPop, SRem, SMove
Sorted Sets
ZCard, ZCount, ZScore, ZRange, ZRangeByScore, ZRank, ZRevRange, ZRevRangeByScore, ZRevRank, ZAdd, ZIncrBy, ZRem, ZRemRangeByRank, ZRemRangeByScore
Pub/Sub
Publish, Subscribe, PSubscribe, Unsubscribe, PUnsubscribe

19.2.2. Handling commands directly

If you need Redis commands other than the above or want to handle commands directly, use the following function.

class RedisClient {
  void ExecuteCommand(const string &command_name,
                      const std::vector<string> *arguments,
                      const Callback &callback,
                      const SerializationTag &tag = kDefaultSerializationTag);

  Ptr<Reply> ExecuteCommandSync(const string &command_name,
                                const std::vector<string> *arguments,
                                Result *result = NULL);
};
public class RedisClient
{
  public void ExecuteCommand (string command_name,
                              List<string> arguments,
                              Callback callback,
                              Guid tag = default(Guid))

  public Reply ExecuteCommandSync (string command_name,
                                   List<string> arguments,
                                   out RedisClient.Result out_result)
}

To run commands with the above functions, the reply structure for Redis server responses and return value of each Redis command, explained in Redis Commands, must be understood.

class RedisClient {
  struct Reply {
    enum Type {
      kString = 1,
      kArray = 2,
      kInteger = 3,
      kNil = 4,
      kStatus = 5,
      kError = 6
    };

    DECLARE_CLASS_PTR(Reply);

    Type type;
    int64_t integer;
    string str;
    std::vector<Ptr<Reply> > elements;
  };
};
public class RedisClient
{
  public enum ReplyType
  {
    kString = 1,
    kArray = 2,
    kInteger = 3,
    kNil = 4,
    kStatus = 5,
    kError = 6
  }

  public struct Reply
  {
    public ReplyType Type { get; }
    public long Integer { get; }
    public string Str { get; }
    public List<Reply> Elements { get; }
  }
}
kString

In this case, the string is returned as follows. You can get C++ values as str and C# as Str.

redis> GET mykey
"hello"
kArray

In this case, the array is returned as follows. You can get C++ values as elements and C# as Elements.

redis> KEYS *
1) "one"
2) "two"
kInteger

In this case, the integer is returned as follows. You can get C++ values as integer and C# as Integer.

redis> HLEN myhash
(integer) 2
kNil

In this case, nil is returned as follows. There is no value for this, so you can only confirm that C++ is type and C# is Type.

redis> GET notfoundmykey
(nil)
kStatus

In this case, the status is returned as follows. You can get C++ values as str and C# as Str.

redis> SET mykey value
OK
kError

In this case, the error is returned as follows. You can get C++ values as str and C# as Str.

redis> SET mykey value value2
(error) ERR syntax error

19.2.3. Asynchronous command order and tags

When Redis commands are run asynchronously, they enter the queue in the default order. However, if there are 2 or more connections handling Redis commands, these commands are handled in parallel.

This can cause problems when the execution order must be guaranteed. RedisClient supports a feature which bundles Redis commands that must be handled in a guaranteed order as tags, as in Event order and event tags.

Asynchronous functions receive these tags as the last parameter, as follows. If tags are left by default, each Redis command is executed in parallel.

class RedisClient {
  typedef Uuid SerializationTag;
  static const SerializationTag kDefaultSerializationTag;

  void Del(const string &key, const IntegerCallback &callback,
           const SerializationTag &tag = kDefaultSerializationTag);
};
public class RedisClient {
  public void Del (string key, IntegerCallback callback,
                   Guid tag = default(Guid))
};

If the tag value is input as follows, each Redis command is executed sequentially and the callback functions are called in the order of OnDeleted1 => OnDeleted2.

Ptr<RedisClient> the_redis_client;

void Initialize() {
  // ...
}

void OnDeleted1(const RedisClient::Result &result, int64_t value) {
}

void OnDeleted2(const RedisClient::Result &result, int64_t value) {
}

void Example() {
  RedisClient::SerializationTag tag = RandomGenerator::GenerateUuid();
  the_redis_client->Del("hello1", OnDeleted1, tag);
  the_redis_client->Del("hello2", OnDeleted2, tag);
}
Ptr<RedisClient> the_redis_client;

void Initialize()
{
  // ...
}

void OnDeleted1(RedisClient.Result result, long value)
{
}

void OnDeleted2(RedisClient.Result result, long value)
{
}

void Example()
{
  System.Guid tag = RandomGenerator.GenerateUuid ();
  the_redis_client.Del("hello1", OnDeleted1, tag);
  the_redis_client.Del("hello2", OnDeleted2, tag);
}

19.3. Example of use

19.3.1. Example - Saving user data

The following example shows user data saved as HMSet when a user logs in.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Ptr<RedisClient> the_redis_client;

void Initialize() {
  the_redis_client = RedisClient::Create("127.0.0.1", 6379, "", 4);
  the_redis_client->Initialize();
}

void OnUserDataWrote(const RedisClient::Result &result, const string &value) {
  if (result.type == RedisClient::kError) {
    LOG(ERROR) << "Error: type=" << result.type
               << ", code=" << result.error_code
               << ", desc=" << result.error_desc;
    return;
  }

  LOG_ASSERT(value == "OK");

  LOG(INFO) << "User data wrote.";
}

void OnLogin(const Ptr<Session> &session, const Json &message) {
  string user_id = message["user_id"].GetString();
  string login_time = WallClock::GetTimestring(WallClock::Now());

  // std::vector<std::pair<string, string > >
  RedisClient::StringPairList field_values;
  field_values.push_back(std::make_pair(user_id, login_time));

  the_redis_client->HMSet("user:data", field_values, OnUserDataWrote);
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
RedisClient the_redis_client;

void Initialize()
{
  the_redis_client = RedisClient.Create("127.0.0.1", 6379, "", 4);
  the_redis_client.Initialize();
}

void OnUserDataWrote(RedisClient.Result result, string value)
{
  if (result.Type == RedisClient.ResultType.kError) {
    Log.Error("Error: type={0}, code={1}, desc={2}",
              result.Type, result.ErrorCode, result.ErrorDesc);
    return;
  }

  Log.Assert(value == "OK");

  Log.Info("User data wrote.");
}

void OnLogin (Session session, JObject message)
{
  string user_id = (string) message["user_id"];
  string login_time = WallClock.GetTimestring();

  List<Tuple<string, string>> field_values = new List<Tuple<string, string>> ();
  field_values.Add (Tuple.Create (user_id, login_time));

  the_redis_client.HMSet("user:data", field_values, OnUserDataWrote);
}

19.3.2. Example - ExecuteCommand()

The following example shows the example handled with HMSet saved as an ExecuteCommand() function.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
Ptr<RedisClient> the_redis_client;

void Initialize() {
  the_redis_client = RedisClient::Create("127.0.0.1", 6379, "", 4);
  the_redis_client->Initialize();
}

void OnUserDataWrote(const RedisClient::Result &result,
                     const Ptr<RedisClient::Reply> &reply) {
  if (result.type == RedisClient::kError) {
    LOG(ERROR) << "Error: type=" << result.type
               << ", code=" << result.error_code
               << ", desc=" << result.error_desc;
    return;
  }

  LOG_ASSERT(reply)
  LOG_ASSERT(reply->type == RedisClient::Reply::kStatus &&
             reply->str == "OK");

  LOG(INFO) << "User data wrote.";
}

void OnLogin(const Ptr<Session> &session, const Json &message) {
  string key = "user:data";
  string user_id = message["user_id"].GetString();
  string login_time = WallClock::GetTimestring(WallClock::Now());

  std::vector<string> arguments;
  arguments.push_back(key);
  arguments.push_back(user_id);
  arguments.push_back(login_time);

  the_redis_client->ExecuteCommand("HMSET", &arguments, OnUserDataWrote);
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
RedisClient the_redis_client;

void Initialize()
{
  the_redis_client = RedisClient.Create("127.0.0.1", 6379, "", 4);
  the_redis_client.Initialize();
}

void OnUserDataWrote(RedisClient.Result result, RedisClient.Reply reply)
{
  if (result.Type == RedisClient.ResultType.kError) {
    Log.Error("Error: type={0}, code={1}, desc={2}",
              result.Type, result.ErrorCode, result.ErrorDesc);
    return;
  }

  Log.Assert(reply.Type == RedisClient.ReplyType.kStatus &&
             reply.Str == "OK");

  Log.Info("User data wrote.");
}

void OnLogin (Session session, JObject message)
{
  string key = "user:data";
  string user_id = (string) message["user_id"];
  string login_time = WallClock.GetTimestring();

  List<string> arguments = new List<string> ();
  arguments.Add (key);
  arguments.Add (user_id);
  arguments.Add (login_time);

  the_redis_client.ExecuteCommand("HMSET", arguments, OnUserDataWrote);
}

19.3.2.1. Redis replication

Note

This will be supported later.

19.3.2.2. Redis clustering

Note

iFun Engine itself does not support Redis clustering.