X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=src%2Fshared%2Fstrbuf.c;h=915cd3ac99bc4ae6491512d2628e26d667a36f6a;hp=5c858cb68e1832e354bec226d12a43b137338383;hb=55c0b89c575fcb2c075286d444ed4fb1cf8c8563;hpb=955bd501c20ad0bc64104ed706225a824dafc375

diff --git a/src/shared/strbuf.c b/src/shared/strbuf.c
index 5c858cb68..915cd3ac9 100644
--- a/src/shared/strbuf.c
+++ b/src/shared/strbuf.c
@@ -3,7 +3,7 @@
 /***
   This file is part of systemd.
 
-  Copyright 2012 Kay Sievers <kay.sievers@vrfy.org>
+  Copyright 2012 Kay Sievers <kay@vrfy.org>
 
   systemd is free software; you can redistribute it and/or modify it
   under the terms of the GNU Lesser General Public License as published by
@@ -25,6 +25,24 @@
 #include "util.h"
 #include "strbuf.h"
 
+/*
+ * Strbuf stores given strings in a single continous allocated memory
+ * area. Identical strings are de-duplicated and return the same offset
+ * as the first string stored. If the tail of a string already exists
+ * in the buffer, the tail is returned.
+ *
+ * A trie (http://en.wikipedia.org/wiki/Trie) is used to maintain the
+ * information about the stored strings.
+ *
+ * Example of udev rules:
+ *   $ ./udevadm test .
+ *   ...
+ *   read rules file: /usr/lib/udev/rules.d/99-systemd.rules
+ *   rules contain 196608 bytes tokens (16384 * 12 bytes), 39742 bytes strings
+ *   23939 strings (207859 bytes), 20404 de-duplicated (171653 bytes), 3536 trie nodes used
+ *   ...
+ */
+
 struct strbuf *strbuf_new(void) {
         struct strbuf *str;
 
@@ -58,6 +76,7 @@ static void strbuf_node_cleanup(struct strbuf_node *node) {
         free(node);
 }
 
+/* clean up trie data, leave only the string buffer */
 void strbuf_complete(struct strbuf *str) {
         if (!str)
                 return;
@@ -66,6 +85,7 @@ void strbuf_complete(struct strbuf *str) {
         str->root = NULL;
 }
 
+/* clean up everything */
 void strbuf_cleanup(struct strbuf *str) {
         if (!str)
                 return;
@@ -82,6 +102,7 @@ static int strbuf_children_cmp(const void *v1, const void *v2) {
         return n1->c - n2->c;
 }
 
+/* add string, return the index/offset into the buffer */
 ssize_t strbuf_add_string(struct strbuf *str, const char *s, size_t len) {
         uint8_t c;
         struct strbuf_node *node;