[redis.git] / doc / HackingStrings.html


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
    <head>
        <link type="text/css" rel="stylesheet" href="style.css" />
    </head>
    <body>
        <div id="page">
        
            <div id='header'>
            <a href="index.html">
            <img style="border:none" alt="Redis Documentation" src="redis.png">
            </a>
            </div>
        
            <div id="pagecontent">
                <div class="index">
<!-- This is a (PRE) block.  Make sure it's left aligned or your toc title will be off. -->
<b>HackingStrings: Contents</b><br>&nbsp;&nbsp;<a href="#Hacking Strings">Hacking Strings</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Creating Redis Strings">Creating Redis Strings</a>
                </div>
                
                <h1 class="wikiname">HackingStrings</h1>

                <div class="summary">
                    
                </div>

                <div class="narrow">
                    
<h1><a name="Hacking Strings">Hacking Strings</a></h1>The implementation of Redis strings is contained in <b></b>sds.c<b></b> ( sds stands for Simple Dynamic Strings ).<br/><br/>The C structure <i>sdshdr</i> declared in <b>sds.h</b> represents a Redis string:<br/><br/><pre class="codeblock python" name="code">
struct sdshdr {
    long len;
    long free;
    char buf[];
};
</pre>The <i>buf</i> character array stores the actual string.<br/><br/>The <i>len</i> field stores the length of <i>buf</i>. This makes obtaining the length
of a Redis string an O(1) operation.<br/><br/>The <i>free</i> field stores the number of additional bytes available for use.<br/><br/>Together the <i>len</i> and <i>free</i> field can be thought of as holding the metadata of the 
<i>buf</i> character array.<h2><a name="Creating Redis Strings">Creating Redis Strings</a></h2>A new data type named <code name="code" class="python">sds</code> is defined in <b>sds.h</b> to be a synonymn for a character pointer:<br/><br/><pre class="codeblock python python" name="code">
typedef char *sds;
</pre><code name="code" class="python">sdsnewlen</code> function defined in <b>sds.c</b> creates a new Redis String: <br/><br/><pre class="codeblock python python python" name="code">
sds sdsnewlen(const void *init, size_t initlen) {
    struct sdshdr *sh;

    sh = zmalloc(sizeof(struct sdshdr)+initlen+1);
#ifdef SDS_ABORT_ON_OOM
    if (sh == NULL) sdsOomAbort();
#else
    if (sh == NULL) return NULL;
#endif
    sh-&gt;len = initlen;
    sh-&gt;free = 0;
    if (initlen) {
        if (init) memcpy(sh-&gt;buf, init, initlen);
        else memset(sh-&gt;buf,0,initlen);
    }
    sh-&gt;buf[initlen] = '\0';
    return (char*)sh-&gt;buf;
}
</pre>Remember a Redis string is a variable of type <code name="code" class="python">struct sdshdr</code>. But <code name="code" class="python">sdsnewlen</code> returns a character pointer!!<br/><br/>That's a trick and needs some explanation.<br/><br/>Suppose I create a Redis string using <code name="code" class="python">sdsnewlen</code> like below:<br/><br/><pre class="codeblock python python python python" name="code">
sdsnewlen(&quot;redis&quot;, 5);
</pre>This creates a new variable of type <code name="code" class="python">struct sdshdr</code> allocating memory for <i>len</i> and <i>free</i>
fields as well as for the <i>buf</i> character array.<br/><br/><pre class="codeblock python python python python python" name="code">
sh = zmalloc(sizeof(struct sdshdr)+initlen+1); // initlen is length of init argument.
</pre>After <code name="code" class="python">sdsnewlen</code> succesfully creates a Redis string the result is something like:<br/><br/><pre class="codeblock python python python python python python" name="code">
-----------
|5|0|redis|
-----------
^   ^
sh  sh-&gt;buf 
</pre><code name="code" class="python">sdsnewlen</code> returns sh-&gt;buf to the caller.<br/><br/>What do you do if you need to free the Redis string pointed by <code name="code" class="python">sh</code>?<br/><br/>You want the pointer <code name="code" class="python">sh</code> but you only have the pointer <code name="code" class="python">sh-&gt;buf</code>.<br/><br/>Can you get the pointer <code name="code" class="python">sh</code> from <code name="code" class="python">sh-&gt;buf</code>?<br/><br/>Yes. Pointer arithmetic. Notice from the above ASCII art that if you subtract 
the size of two longs from <code name="code" class="python">sh-&gt;buf</code> you get the pointer <code name="code" class="python">sh</code>. <br/><br/>The sizeof two longs happens to be the size of <code name="code" class="python">struct sdshdr</code>.<br/><br/>Look at <code name="code" class="python">sdslen</code> function and see this trick at work:<br/><br/><pre class="codeblock python python python python python python python" name="code">
size_t sdslen(const sds s) {
    struct sdshdr *sh = (void*) (s-(sizeof(struct sdshdr)));
    return sh-&gt;len;
}
</pre>Knowing this trick you could easily go through the rest of the functions in <b>sds.c</b>.<br/><br/>The Redis string implementation is hidden behind an interface that accepts only character pointers. The users of Redis strings need not care about how its implemented and treat Redis strings as a character pointer.
                </div>
        
            </div>
        </div>
    </body>
</html>
Commit	Line	Data
aed57a31	1
	2	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
	3	<html>
	4	<head>
	5	<link type="text/css" rel="stylesheet" href="style.css" />
	6	</head>
	7	<body>
	8	<div id="page">
	9
	10	<div id='header'>
	11	<a href="index.html">
	12	<img style="border:none" alt="Redis Documentation" src="redis.png">
	13	</a>
	14	</div>
	15
	16	<div id="pagecontent">
	17	<div class="index">
	18	<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
	19	<b>HackingStrings: Contents</b><br>  <a href="#Hacking Strings">Hacking Strings</a><br>    <a href="#Creating Redis Strings">Creating Redis Strings</a>
	20	</div>
	21
	22	<h1 class="wikiname">HackingStrings</h1>
	23
	24	<div class="summary">
	25
	26	</div>
	27
	28	<div class="narrow">
	29
	30	<h1><a name="Hacking Strings">Hacking Strings</a></h1>The implementation of Redis strings is contained in <b></b>sds.c<b></b> ( sds stands for Simple Dynamic Strings ).<br/><br/>The C structure <i>sdshdr</i> declared in <b>sds.h</b> represents a Redis string:<br/><br/><pre class="codeblock python" name="code">
	31	struct sdshdr {
	32	long len;
	33	long free;
	34	char buf[];
	35	};
	36	</pre>The <i>buf</i> character array stores the actual string.<br/><br/>The <i>len</i> field stores the length of <i>buf</i>. This makes obtaining the length
	37	of a Redis string an O(1) operation.<br/><br/>The <i>free</i> field stores the number of additional bytes available for use.<br/><br/>Together the <i>len</i> and <i>free</i> field can be thought of as holding the metadata of the
	38	<i>buf</i> character array.<h2><a name="Creating Redis Strings">Creating Redis Strings</a></h2>A new data type named <code name="code" class="python">sds</code> is defined in <b>sds.h</b> to be a synonymn for a character pointer:<br/><br/><pre class="codeblock python python" name="code">
	39	typedef char *sds;
	40	</pre><code name="code" class="python">sdsnewlen</code> function defined in <b>sds.c</b> creates a new Redis String: <br/><br/><pre class="codeblock python python python" name="code">
	41	sds sdsnewlen(const void *init, size_t initlen) {
	42	struct sdshdr *sh;
	43
	44	sh = zmalloc(sizeof(struct sdshdr)+initlen+1);
	45	#ifdef SDS_ABORT_ON_OOM
	46	if (sh == NULL) sdsOomAbort();
	47	#else
	48	if (sh == NULL) return NULL;
	49	#endif
	50	sh->len = initlen;
	51	sh->free = 0;
	52	if (initlen) {
	53	if (init) memcpy(sh->buf, init, initlen);
	54	else memset(sh->buf,0,initlen);
	55	}
	56	sh->buf[initlen] = '\0';
	57	return (char*)sh->buf;
	58	}
	59	</pre>Remember a Redis string is a variable of type <code name="code" class="python">struct sdshdr</code>. But <code name="code" class="python">sdsnewlen</code> returns a character pointer!!<br/><br/>That's a trick and needs some explanation.<br/><br/>Suppose I create a Redis string using <code name="code" class="python">sdsnewlen</code> like below:<br/><br/><pre class="codeblock python python python python" name="code">
	60	sdsnewlen("redis", 5);
	61	</pre>This creates a new variable of type <code name="code" class="python">struct sdshdr</code> allocating memory for <i>len</i> and <i>free</i>
	62	fields as well as for the <i>buf</i> character array.<br/><br/><pre class="codeblock python python python python python" name="code">
	63	sh = zmalloc(sizeof(struct sdshdr)+initlen+1); // initlen is length of init argument.
	64	</pre>After <code name="code" class="python">sdsnewlen</code> succesfully creates a Redis string the result is something like:<br/><br/><pre class="codeblock python python python python python python" name="code">
65	-----------
66	\|5\|0\|redis\|
67	-----------
68	^ ^
69	sh sh->buf
70	</pre><code name="code" class="python">sdsnewlen</code> returns sh->buf to the caller.<br/><br/>What do you do if you need to free the Redis string pointed by <code name="code" class="python">sh</code>?<br/><br/>You want the pointer <code name="code" class="python">sh</code> but you only have the pointer <code name="code" class="python">sh->buf</code>.<br/><br/>Can you get the pointer <code name="code" class="python">sh</code> from <code name="code" class="python">sh->buf</code>?<br/><br/>Yes. Pointer arithmetic. Notice from the above ASCII art that if you subtract
71	the size of two longs from <code name="code" class="python">sh->buf</code> you get the pointer <code name="code" class="python">sh</code>. <br/><br/>The sizeof two longs happens to be the size of <code name="code" class="python">struct sdshdr</code>.<br/><br/>Look at <code name="code" class="python">sdslen</code> function and see this trick at work:<br/><br/><pre class="codeblock python python python python python python python" name="code">
72	size_t sdslen(const sds s) {
73	struct sdshdr sh = (void) (s-(sizeof(struct sdshdr)));
74	return sh->len;
75	}
76	</pre>Knowing this trick you could easily go through the rest of the functions in <b>sds.c</b>.<br/><br/>The Redis string implementation is hidden behind an interface that accepts only character pointers. The users of Redis strings need not care about how its implemented and treat Redis strings as a character pointer.
77	</div>
78
79	</div>
80	</div>
81	</body>
82	</html>
83