[master] e67da13 Rename shmem.rst to vsm.rst

Poul-Henning Kamp phk at varnish-cache.org
Thu Nov 24 11:50:55 CET 2011


commit e67da13c4d8d35543ce5b6bfc7092a1efbc6c6de
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date:   Thu Nov 24 10:49:45 2011 +0000

    Rename shmem.rst to vsm.rst

diff --git a/doc/sphinx/Makefile.am b/doc/sphinx/Makefile.am
index dc20abd..d2e5258 100644
--- a/doc/sphinx/Makefile.am
+++ b/doc/sphinx/Makefile.am
@@ -116,7 +116,6 @@ EXTRA_DIST = \
 	phk/three-zero.rst \
 	phk/vcl_expr.rst \
 	reference/index.rst \
-	reference/shmem.rst \
 	reference/params.rst \
 	reference/varnishadm.rst \
 	reference/varnish-cli.rst \
@@ -132,6 +131,7 @@ EXTRA_DIST = \
 	reference/vcl.rst \
 	reference/vmod.rst \
 	reference/vmod_std.rst \
+	reference/vsm.rst \
 	tutorial/advanced_backend_servers.rst \
 	tutorial/advanced_topics.rst \
 	tutorial/backend_servers.rst \
diff --git a/doc/sphinx/reference/index.rst b/doc/sphinx/reference/index.rst
index 84449da..3af59c9 100644
--- a/doc/sphinx/reference/index.rst
+++ b/doc/sphinx/reference/index.rst
@@ -18,7 +18,7 @@ The Varnish Reference Manual
 	varnishstat.rst
 	varnishtest.rst
 	varnishtop.rst
-	shmem.rst
+	vsm.rst
 	vmod.rst
 	vmod_std.rst
 	vsl.rst
diff --git a/doc/sphinx/reference/shmem.rst b/doc/sphinx/reference/shmem.rst
deleted file mode 100644
index 26c5525..0000000
--- a/doc/sphinx/reference/shmem.rst
+++ /dev/null
@@ -1,65 +0,0 @@
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Shared Memory Logging and Statistics
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-Varnish uses shared memory for logging and statistics, because it
-is faster and much more efficient.  But it is also tricky in ways
-a regular logfile is not.
-
-When you open a file in "append" mode, the operating system guarantees
-that whatever you write will not overwrite existing data in the file.
-The neat result of this is that multiple procesess or threads writing
-to the same file does not even need to know about each other, it all
-works just as you would expect.
-
-With a shared memory log, we get no help from the kernel, the writers
-need to make sure they do not stomp on each other, and they need to
-make it possible and safe for the readers to access the data.
-
-The "CS101" way, is to introduce locks, and much time is spent examining
-the relative merits of the many kinds of locks available.
-
-Inside the varnishd (worker) process, we use mutexes to guarantee
-consistency, both with respect to allocations, log entries and stats
-counters.
-
-We do not want a varnishncsa trying to push data through a stalled
-ssh connection to stall the delivery of content, so readers like
-that are purely read-only, they do not get to affect the varnishd
-process and that means no locks for them.
-
-Instead we use "stable storage" concepts, to make sure the view
-seen by the readers is consistent at all times.
-
-As long as you only add stuff, that is trivial, but taking away
-stuff, such as when a backend is taken out of the configuration,
-we need to give the readers a chance to discover this, a "cooling
-off" period.
-
-When Varnishd starts, if it finds an existing shared memory file,
-and it can safely read the master_pid field, it will check if that
-process is running, and if so, fail with an error message, indicating
-that -n arguments collide.
-
-In all other cases, it will delete and create a new shmlog file,
-in order to provide running readers a cooling off period, where
-they can discover that there is a new shmlog file, by doing a
-stat(2) call and checking the st_dev & st_inode fields.
-
-Allocations
------------
-
-Sections inside the shared memory file are allocated dynamically,
-for instance when a new backend is added.
-
-While changes happen to the linked list of allocations, the "alloc_seq"
-header field is zero, and after the change, it gets a value different
-from what it had before.
-
-Deallocations
--------------
-
-When a section is freed, its class will change to "Cool" for at
-least 10 seconds, giving programs using it time to detect the 
-change in alloc_seq header field and/or the change of class.
-
diff --git a/doc/sphinx/reference/vsm.rst b/doc/sphinx/reference/vsm.rst
new file mode 100644
index 0000000..26c5525
--- /dev/null
+++ b/doc/sphinx/reference/vsm.rst
@@ -0,0 +1,65 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+Shared Memory Logging and Statistics
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Varnish uses shared memory for logging and statistics, because it
+is faster and much more efficient.  But it is also tricky in ways
+a regular logfile is not.
+
+When you open a file in "append" mode, the operating system guarantees
+that whatever you write will not overwrite existing data in the file.
+The neat result of this is that multiple procesess or threads writing
+to the same file does not even need to know about each other, it all
+works just as you would expect.
+
+With a shared memory log, we get no help from the kernel, the writers
+need to make sure they do not stomp on each other, and they need to
+make it possible and safe for the readers to access the data.
+
+The "CS101" way, is to introduce locks, and much time is spent examining
+the relative merits of the many kinds of locks available.
+
+Inside the varnishd (worker) process, we use mutexes to guarantee
+consistency, both with respect to allocations, log entries and stats
+counters.
+
+We do not want a varnishncsa trying to push data through a stalled
+ssh connection to stall the delivery of content, so readers like
+that are purely read-only, they do not get to affect the varnishd
+process and that means no locks for them.
+
+Instead we use "stable storage" concepts, to make sure the view
+seen by the readers is consistent at all times.
+
+As long as you only add stuff, that is trivial, but taking away
+stuff, such as when a backend is taken out of the configuration,
+we need to give the readers a chance to discover this, a "cooling
+off" period.
+
+When Varnishd starts, if it finds an existing shared memory file,
+and it can safely read the master_pid field, it will check if that
+process is running, and if so, fail with an error message, indicating
+that -n arguments collide.
+
+In all other cases, it will delete and create a new shmlog file,
+in order to provide running readers a cooling off period, where
+they can discover that there is a new shmlog file, by doing a
+stat(2) call and checking the st_dev & st_inode fields.
+
+Allocations
+-----------
+
+Sections inside the shared memory file are allocated dynamically,
+for instance when a new backend is added.
+
+While changes happen to the linked list of allocations, the "alloc_seq"
+header field is zero, and after the change, it gets a value different
+from what it had before.
+
+Deallocations
+-------------
+
+When a section is freed, its class will change to "Cool" for at
+least 10 seconds, giving programs using it time to detect the 
+change in alloc_seq header field and/or the change of class.
+



More information about the varnish-commit mailing list