Differences

This shows you the differences between two versions of the page.

--- dev:shared_strings [2007/03/22 08:19] – external edit 127.0.0.1
+++ dev:shared_strings [2025/04/18 13:08] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
-To minimize memory use, Crossfire uses a shared string mechanism. This is intended to be used for strings whose contents is not expected to change during the server's life. Using shared strings saves memory and improved performance.
+====== Shared String ======
-Those strings are used like regular ''const char*'', but should not be changed via ''strcpy'', ''snprintf'' or other means because it would affect **all** structures using the shared string. Internally, they use a counter to track at how many places they are used. When it reaches 0, string is freed.
+To minimize memory use, Crossfire uses a shared string mechanism. \\
+This is intended to be used for strings whose contents are not expected to change during the server's life. \\
+Using shared strings saves memory and improved performance.
+Those strings are used like regular ''const char*'', \\
+but should not be changed via ''strcpy'', ''snprintf'' or other means \\
+because it would affect **all** structures using the shared string. \\
+Internally, they use a counter to track at how many places they are used. \\
+When it reaches 0, string is freed.
+----
+===== Shared String Manipulation ==
 To alter such a string, the right behaviour is:
   * write new value in a ''char[] new_value'' variable
@@ Line 8: / Line 19: @@
   * call ''str = add_string(new_value)''
-FIXME replace with sstring when done in code
+To manipulate them, the following functions defined in \\
+[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/common/shstr.c?view=markup|common/shstr.c]]  <- FIXME file location \\
+are available:
+  * Old: ''const char* add_string(const char *str)''
+  * New: ** ''sstring add_string(const char *str)'' **
+    * Used to share an existing string.
+    * Returned value is a string with the same contents of ''str'' that can be shared with other objects.
+    * Returns return hash_table[ind]->string
+  * Old: ''const char* add_refcount(const char *str)''
+  * New: ** ''sstring add_refcount(sstring str)'' **
+    * This will increase the refcount of the string str.
+    * String str which *must* have been returned from a previous add_string().
+    * :?: Equivalent of ''add_string'' when the string is already a shared string. :?:
+  * Old: ''const char* find_string(const char *str)''
+  * New: ** ''sstring find_string(const char *str)'' **
+    * To search if a string is shared or not.
+    * Returns pointer to identical string or NULL .
+  * Old: ''void free_string(const char *str)''
+  * New: ** ''void free_string(sstring str)'' **
+    * To decrement the use refcount counter.
+    * *Must* have been returned from a previous add_string().
+    * After it's called, ''str'' should not be used anymore.
+Because shared strings will return a pointer to a string if it exists, \\
+one can see if the strings are equal by comparing the shared string address they point to (ie ''str == str2'') directly.
+----
+===== SSTRING =====
+sstring is defined in //server/include/shstr.h// since at least version 1.11.0 :
+<code c>
+/**
+ * One actual shared string.
+ */
+typedef struct _shared_string {
+    union {
+        struct _shared_string **array;
+        struct _shared_string *previous;
+    } u;
+    struct _shared_string *next;
+    /* The top bit of "refcount" is used to signify that "u.array" points
+     * at the array entry.
+     */
+    unsigned REFCOUNT_TYPE refcount;
+    /* Padding will be unused memory, since we can't know how large
+     * the padding when allocating memory. We assume here that
+     * sizeof(long) is a good boundary.
+     */
+    char string[PADDING];
+} shared_string;
+</code>
+----
-To manipulate them, the following functions (defined in ''[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/common/shstr.c?view=markup|common/shstr.c]]'') are available:
+===== Trivial ==
-  * ''const char* add_string(const char *str)'', used to share a string. Returned value is a string with the same contents that can be shared with other objects
+<code c>
-  * ''const char* add_refcount(const char *str)'', equivalent of ''add_string'' when the string is already a shared string
+/**
-  * ''const char* find_string(const char *str)'', to search if a string is shared or not
+ * @file shstr.c
-  * ''void free_string(const char *str)'', to decrement the use counter. After it's called, ''str'' should not be used anymore.
+ * This is a simple shared strings package with a simple interface.
+ *
+ * Author: Kjetil T. Homme, Oslo 1992.
+ */
+</code>
-Because shared strings will return a pointer to a string if it exists, one can see if the strings are equal by comparing the shared string address they point to (ie ''str == str2'' directly).