summaryrefslogtreecommitdiffstats
path: root/doc/hacker-guide
diff options
context:
space:
mode:
authorLubomir Rintel <lubo.rintel@gooddata.com>2013-08-01 15:39:00 +0200
committerVijay Bellur <vbellur@redhat.com>2013-08-04 07:41:20 -0700
commit78725a148eda42ee9e48677b8df131099389cacc (patch)
tree0a3f708c6a172340bdfdd37f76c35284055ae7e2 /doc/hacker-guide
parenta7564731e30312047f0300760c248f86c1080d84 (diff)
doc: Re-format the translator tutorial
Adjutst whitespace so that things don't overflow in PDF. Change-Id: Ic75abccbe744aac327b1c6311afb4c13271a723d Signed-off-by: Lubomir Rintel <lubo.rintel@gooddata.com> Reviewed-on: http://review.gluster.org/5481 Reviewed-by: Vijay Bellur <vbellur@redhat.com> Tested-by: Vijay Bellur <vbellur@redhat.com>
Diffstat (limited to 'doc/hacker-guide')
-rw-r--r--doc/hacker-guide/en-US/markdown/translator-development.md259
1 files changed, 141 insertions, 118 deletions
diff --git a/doc/hacker-guide/en-US/markdown/translator-development.md b/doc/hacker-guide/en-US/markdown/translator-development.md
index 6e367de54a8..77d1b606ae0 100644
--- a/doc/hacker-guide/en-US/markdown/translator-development.md
+++ b/doc/hacker-guide/en-US/markdown/translator-development.md
@@ -24,27 +24,27 @@ shared-object file, as follow (from `xlator.c`):
```
if (!(xl->fops = dlsym (handle, "fops"))) {
- gf_log ("xlator", GF_LOG_WARNING, "dlsym(fops) on %s",
- dlerror ());
- goto out;
+ gf_log ("xlator", GF_LOG_WARNING, "dlsym(fops) on %s",
+ dlerror ());
+ goto out;
}
if (!(xl->cbks = dlsym (handle, "cbks"))) {
- gf_log ("xlator", GF_LOG_WARNING, "dlsym(cbks) on %s",
- dlerror ());
- goto out;
+ gf_log ("xlator", GF_LOG_WARNING, "dlsym(cbks) on %s",
+ dlerror ());
+ goto out;
}
if (!(xl->init = dlsym (handle, "init"))) {
- gf_log ("xlator", GF_LOG_WARNING, "dlsym(init) on %s",
- dlerror ());
- goto out;
+ gf_log ("xlator", GF_LOG_WARNING, "dlsym(init) on %s",
+ dlerror ());
+ goto out;
}
if (!(xl->fini = dlsym (handle, "fini"))) {
- gf_log ("xlator", GF_LOG_WARNING, "dlsym(fini) on %s",
- dlerror ());
- goto out;
+ gf_log ("xlator", GF_LOG_WARNING, "dlsym(fini) on %s",
+ dlerror ());
+ goto out;
}
```
@@ -61,21 +61,21 @@ translator just for fun, so in this case you'd look in `rot-13.c` to see this:
```
struct xlator_fops fops = {
- .readv = rot13_readv,
- .writev = rot13_writev
+ .readv = rot13_readv,
+ .writev = rot13_writev
};
struct xlator_cbks cbks = {
};
struct volume_options options[] = {
-{ .key = {"encrypt-write"},
+{ .key = {"encrypt-write"},
.type = GF_OPTION_TYPE_BOOL
},
-{ .key = {"decrypt-read"},
+{ .key = {"decrypt-read"},
.type = GF_OPTION_TYPE_BOOL
},
-{ .key = {NULL} },
+{ .key = {NULL} },
};
```
@@ -123,10 +123,10 @@ then come back to `rot-13`.
.type = GF_OPTION_TYPE_STR,
.default_value = "",
.description = "Select between \"full\", \"diff\". The "
- "\"full\" algorithm copies the entire file from "
- "source to sink. The \"diff\" algorithm copies to "
- "sink only those blocks whose checksums don't match "
- "with those of source.",
+ "\"full\" algorithm copies the entire file from "
+ "source to sink. The \"diff\" algorithm copies to "
+ "sink only those blocks whose checksums don't match "
+ "with those of source.",
.value = { "diff", "full", "" }
},
{ .key = {"data-self-heal-window-size"},
@@ -134,8 +134,8 @@ then come back to `rot-13`.
.min = 1,
.max = 1024,
.default_value = "1",
- .description = "Maximum number blocks per file for which self-heal "
- "process would be applied simultaneously."
+ .description = "Maximum number blocks per file for which "
+ "self-heal process would be applied simultaneously."
},
```
@@ -152,11 +152,12 @@ priv->encrypt_write = 1;
data = dict_get (this->options, "encrypt-write");
if (data) {
- if (gf_string2boolean (data->data, &priv->encrypt_write) == -1) {
- gf_log (this->name, GF_LOG_ERROR,
- "encrypt-write takes only boolean options");
- return -1;
- }
+ if (gf_string2boolean (data->data, &priv->encrypt_write
+ == -1) {
+ gf_log (this->name, GF_LOG_ERROR,
+ "encrypt-write takes only boolean options");
+ return -1;
+ }
}
```
@@ -202,23 +203,23 @@ function that we just barely touched on last time.
int32_t
init (xlator_t *this)
{
- data_t *data = NULL;
- rot_13_private_t *priv = NULL;
+ data_t *data = NULL;
+ rot_13_private_t *priv = NULL;
- if (!this->children || this->children->next) {
- gf_log ("rot13", GF_LOG_ERROR,
- "FATAL: rot13 should have exactly one child");
- return -1;
- }
+ if (!this->children || this->children->next) {
+ gf_log ("rot13", GF_LOG_ERROR,
+ "FATAL: rot13 should have exactly one child");
+ return -1;
+ }
- if (!this->parents) {
- gf_log (this->name, GF_LOG_WARNING,
- "dangling volume. check volfile ");
- }
+ if (!this->parents) {
+ gf_log (this->name, GF_LOG_WARNING,
+ "dangling volume. check volfile ");
+ }
- priv = GF_CALLOC (sizeof (rot_13_private_t), 1, 0);
- if (!priv)
- return -1;
+ priv = GF_CALLOC (sizeof (rot_13_private_t), 1, 0);
+ if (!priv)
+ return -1;
```
At the very top, we see the function signature -- we get a pointer to the
@@ -273,20 +274,20 @@ To finish our tour of standard initialization/termination, let's look at the
end of `init` and the beginning of `fini`:
```
- this->private = priv;
- gf_log ("rot13", GF_LOG_DEBUG, "rot13 xlator loaded");
- return 0;
+ this->private = priv;
+ gf_log ("rot13", GF_LOG_DEBUG, "rot13 xlator loaded");
+ return 0;
}
void
fini (xlator_t *this)
{
- rot_13_private_t *priv = this->private;
+ rot_13_private_t *priv = this->private;
- if (!priv)
- return;
- this->private = NULL;
- GF_FREE (priv);
+ if (!priv)
+ return;
+ this->private = NULL;
+ GF_FREE (priv);
```
At the end of init we're just storing our private-data pointer in the `priv`
@@ -336,20 +337,21 @@ TARGET = rot-13.so
OBJECTS = rot-13.o
# Change these to match your environment.
-GLFS_SRC = /play/glusterfs
-GLFS_LIB = /opt/glusterfs/3git/lib64
+GLFS_SRC = /srv/glusterfs
+GLFS_LIB = /usr/lib64
HOST_OS = GF_LINUX_HOST_OS
# You shouldn't need to change anything below here.
CFLAGS = -fPIC -Wall -O0 -g \
- -DHAVE_CONFIG_H -D_FILE_OFFSET_BITS=64 -D_GNU_SOURCE -D$(HOST_OS) \
- -I$(GLFS_SRC) -I$(GLFS_SRC)/libglusterfs/src \
- -I$(GLFS_SRC)/contrib/uuid
-LDFLAGS = -shared -nostartfiles -L$(GLFS_LIB) -lglusterfs -lpthread
+ -DHAVE_CONFIG_H -D_FILE_OFFSET_BITS=64 -D_GNU_SOURCE \
+ -D$(HOST_OS) -I$(GLFS_SRC) -I$(GLFS_SRC)/contrib/uuid \
+ -I$(GLFS_SRC)/libglusterfs/src
+LDFLAGS = -shared -nostartfiles -L$(GLFS_LIB) -lglusterfs \
+ -lpthread
$(TARGET): $(OBJECTS)
- $(CC) $(OBJECTS) $(LDFLAGS) -o $(TARGET)
+ $(CC) $(OBJECTS) $(LDFLAGS) -o $(TARGET)
```
Yes, it's still Linux-specific. Mea culpa. As you can see, we're sticking with
@@ -358,7 +360,7 @@ the `rot-13` example, so you can just copy the files from
`make` and you should be rewarded with a nice little `.so` file.
```
-[jeff@gfs-i8c-01 xlator_example]$ ls -l rot-13.so
+xlator_example$ ls -l rot-13.so
-rwxr-xr-x. 1 jeff jeff 40784 Nov 16 16:41 rot-13.so
```
@@ -369,9 +371,11 @@ on our system, so that it doesn't stomp on the installed version (not that
you'd ever want to use that anyway).
```
-[root@gfs-i8c-01 xlator_example]# ls /opt/glusterfs/3git/lib64/glusterfs/3git/xlator/encryption/
-crypt.so crypt.so.0 crypt.so.0.0.0 rot-13.so rot-13.so.0 rot-13.so.0.0.0
-[root@gfs-i8c-01 xlator_example]# cp rot-13.so /opt/glusterfs/3git/lib64/glusterfs/3git/xlator/encryption/my-rot-13.so
+xlator_example# ls /usr/lib64/glusterfs/3git/xlator/encryption/
+crypt.so crypt.so.0 crypt.so.0.0.0 rot-13.so rot-13.so.0
+rot-13.so.0.0.0
+xlator_example# cp rot-13.so \
+ /usr/lib64/glusterfs/3git/xlator/encryption/my-rot-13.so
```
These paths represent the current Gluster filesystem layout, which is likely to
@@ -384,7 +388,7 @@ volfile. Here's just about the simplest volfile you'll ever see.
```
volume my-posix
type storage/posix
- option directory /play/export
+ option directory /srv/export
end-volume
volume my-rot13
@@ -393,7 +397,7 @@ volume my-rot13
end-volume
```
-All we have here is a basic brick using `/play/export` for its data, and then
+All we have here is a basic brick using `/srv/export` for its data, and then
an instance of our translator layered on top -- no client or server is
necessary for what we're doing, and the system will automatically push a
mount/fuse translator on top if there's no server translator. To try this out,
@@ -401,7 +405,7 @@ all we need is the following command (assuming the directories involved already
exist).
```
-[jeff@gfs-i8c-01 xlator_example]$ glusterfs --debug -f my.vol /play/import
+xlator_example$ glusterfs --debug -f my.vol /srv/import
```
You should be rewarded with a whole lot of log output, including the text of
@@ -410,18 +414,18 @@ go to another window on the same machine, you can see that you have a new
filesystem mounted.
```
-[jeff@gfs-i8c-01 ~]$ df /play/import
-Filesystem 1K-blocks Used Available Use% Mounted on
-/play/xlator_example/my.vol
- 114506240 2706176 105983488 3% /play/import
+~$ df /srv/import
+Filesystem 1K-blocks Used Available Use% Mounted on
+/srv/xlator_example/my.vol
+ 114506240 2706176 105983488 3% /srv/import
```
-Just for fun, write something into a file in `/play/import`, then look at the
-corresponding file in `/play/export` to see it all `rot-13`'ed for you.
+Just for fun, write something into a file in `/srv/import`, then look at the
+corresponding file in `/srv/export` to see it all `rot-13`'ed for you.
```
-[jeff@gfs-i8c-01 ~]$ echo hello > /play/import/a_file
-[jeff@gfs-i8c-01 ~]$ cat /play/export/a_file
+~$ echo hello > /srv/import/a_file
+~$ cat /srv/export/a_file
uryyb
```
@@ -440,26 +444,28 @@ time to run one and actually watch it work. The best way to do this is good
old-fashioned `gdb`, as follows (using some of the examples from last time).
```
-[root@gfs-i8c-01 xlator_example]# gdb glusterfs
+xlator_example# gdb glusterfs
GNU gdb (GDB) Red Hat Enterprise Linux (7.2-50.el6)
...
-(gdb) r --debug -f my.vol /play/import
-Starting program: /usr/sbin/glusterfs --debug -f my.vol /play/import
+(gdb) r --debug -f my.vol /srv/import
+Starting program: /usr/sbin/glusterfs --debug -f my.vol /srv/import
...
-[2011-11-23 11:23:16.495516] I [fuse-bridge.c:2971:fuse_init] 0-glusterfs-fuse: FUSE inited with protocol versions: glusterfs 7.13 kernel 7.13
+[2011-11-23 11:23:16.495516] I [fuse-bridge.c:2971:fuse_init]
+ 0-glusterfs-fuse: FUSE inited with protocol versions:
+ glusterfs 7.13 kernel 7.13
```
If you get to this point, your glusterfs client process is already running. You
can go to another window to see the mountpoint, do file operations, etc.
```
-[root@gfs-i8c-01 ~]# df /play/import
-Filesystem 1K-blocks Used Available Use% Mounted on
+~# df /srv/import
+Filesystem 1K-blocks Used Available Use% Mounted on
/root/xlator_example/my.vol
- 114506240 2643968 106045568 3% /play/import
-[root@gfs-i8c-01 ~]# ls /play/import
+ 114506240 2643968 106045568 3% /srv/import
+~# ls /srv/import
a_file
-[root@gfs-i8c-01 ~]# cat /play/import/a_file
+~# cat /srv/import/a_file
hello
```
@@ -468,15 +474,24 @@ Now let's interrupt the process and see where we are.
```
^C
Program received signal SIGINT, Interrupt.
-0x0000003a0060b3dc in pthread_cond_wait@@GLIBC_2.3.2 () from /lib64/libpthread.so.0
+0x0000003a0060b3dc in pthread_cond_wait@@GLIBC_2.3.2 ()
+ from /lib64/libpthread.so.0
(gdb) info threads
- 5 Thread 0x7fffeffff700 (LWP 27206) 0x0000003a002dd8c7 in readv ()
- from /lib64/libc.so.6
- 4 Thread 0x7ffff50e3700 (LWP 27205) 0x0000003a0060b75b in pthread_cond_timedwait@@GLIBC_2.3.2 () from /lib64/libpthread.so.0
- 3 Thread 0x7ffff5f02700 (LWP 27204) 0x0000003a0060b3dc in pthread_cond_wait@@GLIBC_2.3.2 () from /lib64/libpthread.so.0
- 2 Thread 0x7ffff6903700 (LWP 27203) 0x0000003a0060f245 in sigwait ()
- from /lib64/libpthread.so.0
-* 1 Thread 0x7ffff7957700 (LWP 27196) 0x0000003a0060b3dc in pthread_cond_wait@@GLIBC_2.3.2 () from /lib64/libpthread.so.0
+ 5 Thread 0x7fffeffff700 (LWP 27206) 0x0000003a002dd8c7
+ in readv ()
+ from /lib64/libc.so.6
+ 4 Thread 0x7ffff50e3700 (LWP 27205) 0x0000003a0060b75b
+ in pthread_cond_timedwait@@GLIBC_2.3.2 ()
+ from /lib64/libpthread.so.0
+ 3 Thread 0x7ffff5f02700 (LWP 27204) 0x0000003a0060b3dc
+ in pthread_cond_wait@@GLIBC_2.3.2 ()
+ from /lib64/libpthread.so.0
+ 2 Thread 0x7ffff6903700 (LWP 27203) 0x0000003a0060f245
+ in sigwait ()
+ from /lib64/libpthread.so.0
+* 1 Thread 0x7ffff7957700 (LWP 27196) 0x0000003a0060b3dc
+ in pthread_cond_wait@@GLIBC_2.3.2 ()
+ from /lib64/libpthread.so.0
```
Like any non-toy server, this one has multiple threads. What are they all
@@ -504,13 +519,14 @@ Continuing.
At this point we go into our other window and do something that will involve a write.
```
-[root@gfs-i8c-01 ~]# echo goodbye > /play/import/another_file
+~# echo goodbye > /srv/import/another_file
(back to the first window)
[Switching to Thread 0x7fffeffff700 (LWP 27206)]
-Breakpoint 1, rot13_writev (frame=0x7ffff6e4402c, this=0x638440, fd=0x7ffff409802c,
- vector=0x7fffe8000cd8, count=1, offset=0, iobref=0x7fffe8001070) at rot-13.c:119
-119 rot_13_private_t *priv = (rot_13_private_t *)this->private;
+Breakpoint 1, rot13_writev (frame=0x7ffff6e4402c, this=0x638440,
+ fd=0x7ffff409802c, vector=0x7fffe8000cd8, count=1, offset=0,
+ iobref=0x7fffe8001070) at rot-13.c:119
+119 rot_13_private_t *priv = (rot_13_private_t *)this->private;
```
Remember how we built with debugging symbols enabled and no optimization? That
@@ -542,7 +558,7 @@ written, like this.
(gdb) p vector[0]
$2 = {iov_base = 0x7ffff7936000, iov_len = 8}
(gdb) x/s 0x7ffff7936000
-0x7ffff7936000: "goodbye\n"
+0x7ffff7936000: "goodbye\n"
```
It's not always safe to view this data as a string, because it might just as
@@ -551,21 +567,21 @@ and convenient. With that knowledge, let's step through things a bit.
```
(gdb) s
-120 if (priv->encrypt_write)
+120 if (priv->encrypt_write)
(gdb)
-121 rot13_iovec (vector, count);
+121 rot13_iovec (vector, count);
(gdb)
rot13_iovec (vector=0x7fffe8000cd8, count=1) at rot-13.c:57
-57 for (i = 0; i < count; i++) {
+57 for (i = 0; i < count; i++) {
(gdb)
-58 rot13 (vector[i].iov_base, vector[i].iov_len);
+58 rot13 (vector[i].iov_base, vector[i].iov_len);
(gdb)
rot13 (buf=0x7ffff7936000 "goodbye\n", len=8) at rot-13.c:45
-45 for (i = 0; i < len; i++) {
+45 for (i = 0; i < len; i++) {
(gdb)
-46 if (buf[i] >= 'a' && buf[i] <= 'z')
+46 if (buf[i] >= 'a' && buf[i] <= 'z')
(gdb)
-47 buf[i] = 'a' + ((buf[i] - 'a' + 13) % 26);
+47 buf[i] = 'a' + ((buf[i] - 'a' + 13) % 26);
```
Here we've stepped into `rot13_iovec`, which iterates through our vector
@@ -575,14 +591,17 @@ stuff, so let's skip to the next interesting bit.
```
(gdb) fin
-Run till exit from #0 rot13 (buf=0x7ffff7936000 "goodbye\n", len=8) at rot-13.c:47
+Run till exit from #0 rot13 (buf=0x7ffff7936000 "goodbye\n",
+ len=8) at rot-13.c:47
rot13_iovec (vector=0x7fffe8000cd8, count=1) at rot-13.c:57
-57 for (i = 0; i < count; i++) {
+57 for (i = 0; i < count; i++) {
(gdb) fin
-Run till exit from #0 rot13_iovec (vector=0x7fffe8000cd8, count=1) at rot-13.c:57
-rot13_writev (frame=0x7ffff6e4402c, this=0x638440, fd=0x7ffff409802c,
- vector=0x7fffe8000cd8, count=1, offset=0, iobref=0x7fffe8001070) at rot-13.c:123
-123 STACK_WIND (frame,
+Run till exit from #0 rot13_iovec (vector=0x7fffe8000cd8,
+ count=1) at rot-13.c:57
+rot13_writev (frame=0x7ffff6e4402c, this=0x638440,
+ fd=0x7ffff409802c, vector=0x7fffe8000cd8, count=1,
+ offset=0, iobref=0x7fffe8001070) at rot-13.c:123
+123 STACK_WIND (frame,
(gdb) b 129
Breakpoint 2 at 0x7ffff50e4f35: file rot-13.c, line 129.
(gdb) b rot13_writev_cbk
@@ -594,21 +613,25 @@ So we've set breakpoints on both the callback and the statement following the
`STACK_WIND`. Which one will we hit first?
```
-Breakpoint 3, rot13_writev_cbk (frame=0x7ffff6e4402c, cookie=0x7ffff6e440d8,
- this=0x638440, op_ret=8, op_errno=0, prebuf=0x7fffefffeca0,
- postbuf=0x7fffefffec30) at rot-13.c:106
-106 STACK_UNWIND_STRICT (writev, frame, op_ret, op_errno, prebuf, postbuf);
+Breakpoint 3, rot13_writev_cbk (frame=0x7ffff6e4402c,
+ cookie=0x7ffff6e440d8, this=0x638440, op_ret=8, op_errno=0,
+ prebuf=0x7fffefffeca0, postbuf=0x7fffefffec30)
+ at rot-13.c:106
+106 STACK_UNWIND_STRICT (writev, frame, op_ret, op_errno,
+ prebuf, postbuf);
(gdb) bt
-#0 rot13_writev_cbk (frame=0x7ffff6e4402c, cookie=0x7ffff6e440d8, this=0x638440,
- op_ret=8, op_errno=0, prebuf=0x7fffefffeca0, postbuf=0x7fffefffec30)
+#0 rot13_writev_cbk (frame=0x7ffff6e4402c,
+ cookie=0x7ffff6e440d8, this=0x638440, op_ret=8, op_errno=0,
+ prebuf=0x7fffefffeca0, postbuf=0x7fffefffec30)
at rot-13.c:106
#1 0x00007ffff52f1b37 in posix_writev (frame=0x7ffff6e440d8,
this=<value optimized out>, fd=<value optimized out>,
- vector=<value optimized out>, count=1, offset=<value optimized out>,
- iobref=0x7fffe8001070) at posix.c:2217
-#2 0x00007ffff50e513e in rot13_writev (frame=0x7ffff6e4402c, this=0x638440,
- fd=0x7ffff409802c, vector=0x7fffe8000cd8, count=1, offset=0,
- iobref=0x7fffe8001070) at rot-13.c:123
+ vector=<value optimized out>, count=1,
+ offset=<value optimized out>, iobref=0x7fffe8001070)
+ at posix.c:2217
+#2 0x00007ffff50e513e in rot13_writev (frame=0x7ffff6e4402c,
+ this=0x638440, fd=0x7ffff409802c, vector=0x7fffe8000cd8,
+ count=1, offset=0, iobref=0x7fffe8001070) at rot-13.c:123
```
Surprise! We're in `rot13_writev_cbk` now, called (indirectly) while we're