Fossil SCM

Improvements to backoffice documentation.

drh 2020-07-02 13:09 trunk

Commit 8a4b5c42d5958c9b23adea8b35860a28b673e3136ef83029b62c5f56743fb953

Parent 75b76efbba2a5c9…

2 files changed +9 -7 +38 -2

M src/backoffice.c

+9 -7

		--- src/backoffice.c
		+++ src/backoffice.c
		@@ -653,11 +653,11 @@
653	653	** repository is specified, run it on the repository of the local checkout.
654	654	**
655	655	** This might be done by a cron job or similar to make sure backoffice
656	656	** processing happens periodically. Or, the --poll option can be used
657	657	** to run this command as a daemon that will periodically invoke backoffice
658		-** on collection of repositories.
	658	+** on a collection of repositories.
659	659	**
660	660	** If only a single repository is named and --poll is omitted, the the
661	661	** backoffice work is done in-process. But if there are multiple respositories
662	662	** or if --poll is used, a separate sub-process is started for each poll of
663	663	** each repository.
		@@ -671,26 +671,28 @@
671	671	** --min N When polling, invoke backoffice at least
672	672	** once every N seconds even if the repository
673	673	** never changes. 0 or negative means disable
674	674	** this feature. Default: 3600 (once per hour).
675	675	**
676		-** --nodelay Do not queue up or wait for a backoffice job
677		-** to complete. If no work is available or if
678		-** backoffice has run recently, return immediately.
679		-**
680	676	** --poll N Repeat backoffice calls for repositories that
681	677	** change in appoximately N-second intervals.
682	678	** N less than 1 turns polling off (the default).
683	679	** Recommended polling interval: 60 seconds.
684	680	**
685	681	** --trace Enable debugging output on stderr
686	682	**
687	683	** Options intended for internal use only which may change or be
688		-** discontinued in a future release:
	684	+** discontinued in future releases:
	685	+**
	686	+** --nodelay Do not queue up or wait for a backoffice job
	687	+** to complete. If no work is available or if
	688	+** backoffice has run recently, return immediately.
689	689	**
690	690	** --nolease Always run backoffice, even if there is a lease
691		-** conflict. This option implies --nodelay.
	691	+** conflict. This option implies --nodelay. This
	692	+** option is added to secondary backoffice commands
	693	+** that are invoked by the --poll option.
692	694	*/
693	695	void backoffice_command(void){
694	696	int nPoll;
695	697	int nMin;
696	698	const char *zPoll;
697	699

	--- src/backoffice.c
	+++ src/backoffice.c
	@@ -653,11 +653,11 @@
653	** repository is specified, run it on the repository of the local checkout.
654	**
655	** This might be done by a cron job or similar to make sure backoffice
656	** processing happens periodically. Or, the --poll option can be used
657	** to run this command as a daemon that will periodically invoke backoffice
658	** on collection of repositories.
659	**
660	** If only a single repository is named and --poll is omitted, the the
661	** backoffice work is done in-process. But if there are multiple respositories
662	** or if --poll is used, a separate sub-process is started for each poll of
663	** each repository.
	@@ -671,26 +671,28 @@
671	** --min N When polling, invoke backoffice at least
672	** once every N seconds even if the repository
673	** never changes. 0 or negative means disable
674	** this feature. Default: 3600 (once per hour).
675	**
676	** --nodelay Do not queue up or wait for a backoffice job
677	** to complete. If no work is available or if
678	** backoffice has run recently, return immediately.
679	**
680	** --poll N Repeat backoffice calls for repositories that
681	** change in appoximately N-second intervals.
682	** N less than 1 turns polling off (the default).
683	** Recommended polling interval: 60 seconds.
684	**
685	** --trace Enable debugging output on stderr
686	**
687	** Options intended for internal use only which may change or be
688	** discontinued in a future release:




689	**
690	** --nolease Always run backoffice, even if there is a lease
691	** conflict. This option implies --nodelay.


692	*/
693	void backoffice_command(void){
694	int nPoll;
695	int nMin;
696	const char *zPoll;
697

	--- src/backoffice.c
	+++ src/backoffice.c
	@@ -653,11 +653,11 @@
653	** repository is specified, run it on the repository of the local checkout.
654	**
655	** This might be done by a cron job or similar to make sure backoffice
656	** processing happens periodically. Or, the --poll option can be used
657	** to run this command as a daemon that will periodically invoke backoffice
658	** on a collection of repositories.
659	**
660	** If only a single repository is named and --poll is omitted, the the
661	** backoffice work is done in-process. But if there are multiple respositories
662	** or if --poll is used, a separate sub-process is started for each poll of
663	** each repository.
	@@ -671,26 +671,28 @@
671	** --min N When polling, invoke backoffice at least
672	** once every N seconds even if the repository
673	** never changes. 0 or negative means disable
674	** this feature. Default: 3600 (once per hour).
675	**




676	** --poll N Repeat backoffice calls for repositories that
677	** change in appoximately N-second intervals.
678	** N less than 1 turns polling off (the default).
679	** Recommended polling interval: 60 seconds.
680	**
681	** --trace Enable debugging output on stderr
682	**
683	** Options intended for internal use only which may change or be
684	** discontinued in future releases:
685	**
686	** --nodelay Do not queue up or wait for a backoffice job
687	** to complete. If no work is available or if
688	** backoffice has run recently, return immediately.
689	**
690	** --nolease Always run backoffice, even if there is a lease
691	** conflict. This option implies --nodelay. This
692	** option is added to secondary backoffice commands
693	** that are invoked by the --poll option.
694	*/
695	void backoffice_command(void){
696	int nPoll;
697	int nMin;
698	const char *zPoll;
699

M www/backoffice.md

+38 -2

		--- www/backoffice.md
		+++ www/backoffice.md
		@@ -55,11 +55,13 @@
55	55	Windows it is not possible to replace an executable file that is in active
56	56	use. But Windows users probably already know this.)
57	57
58	58	The backoffice is serialized and rate limited. No more than a single
59	59	backoffice process will be running at once, and backoffice runs will not
60		-occur more frequently than once every 60 seconds.
	60	+occur more frequently than once every 60 seconds. (The 60-second spacing
	61	+is controlled by the BKOFCE_LEASE_TIME macro in the
	62	+[backoffice.c](/file/src/backoffice.c) source file.)
61	63
62	64	If a Fossil server is idle, then no backoffice processes will be running.
63	65	That means there are no extra processes sitting around taking up memory
64	66	and process table slots for seldom accessed repositories.
65	67	The backoffice is an on-demand system.
		@@ -87,14 +89,48 @@
87	89	per day from random robots, which will be sufficient to kick off the
88	90	daily digest emails. And even for a private server, if there is very
89	91	little traffic, then the daily digests are probably a no-op anyhow
90	92	and won't be missed.
91	93
	94	+Automatic Backoffice Does Not Work On Some Systems
	95	+--------------------------------------------------
	96	+
	97	+We have observed that the automatic backoffice does not work on
	98	+some system - OpenBSD in particular. We still do not understand why
	99	+this is. (If you have insights, please share them on the
	100	+[Fossil Forum](https://fossil-scm.org/forum) so that we can perhaps
	101	+fix the problem.) For now, the backoffice must be run manually
	102	+on OpenBSD systems.
	103	+
	104	+To set up fully-manual backoffice, first disable the automatic backoffice
	105	+using the "[backoffice-disable](/help?cmd=backoffice-disable)" setting.
	106	+
	107	+> fossil setting backoffice-disable on
	108	+
	109	+Then arrange to invoke the backoffice separately using a command
	110	+like this:
	111	+
	112	+> fossil backoffice --poll 30 _REPOSITORY-LIST_
	113	+
	114	+Multiple repositories can be named. This one command will handle
	115	+launching the backoffice for all of them. There are additional useful
	116	+command-line options. See the "[fossil backoffice](/help?cmd=backoffice)"
	117	+documentation for details.
	118	+
	119	+The backoffice processes run manually using the "fossil backoffice"
	120	+command do not normally use a lease. That means that you run the
	121	+"fossil backoffice" command with --poll and you forget to disable
	122	+automatic backoffice by setting the "backoffice-disable" flag, then
	123	+you might have one backoffice running due command and another due
	124	+to a webpage access, both at the same time. This is harmless. The
	125	+only downside is that it uses extra CPU time.
	126	+
92	127	How Backoffice Is Implemented
93	128	-----------------------------
94	129
95		-The backoffice is implemented by the "backoffice.c" source file.
	130	+The backoffice is implemented by the
	131	+"[backoffice.c](/file/src/backoffice.c)" source file.
96	132
97	133	Serialization and rate limiting is handled by a single entry in the
98	134	repository database CONFIG table named "backoffice". This entry is
99	135	called "the lease". The value of the lease
100	136	is a text string representing four integers, which
101	137

	--- www/backoffice.md
	+++ www/backoffice.md
	@@ -55,11 +55,13 @@
55	Windows it is not possible to replace an executable file that is in active
56	use. But Windows users probably already know this.)
57
58	The backoffice is serialized and rate limited. No more than a single
59	backoffice process will be running at once, and backoffice runs will not
60	occur more frequently than once every 60 seconds.


61
62	If a Fossil server is idle, then no backoffice processes will be running.
63	That means there are no extra processes sitting around taking up memory
64	and process table slots for seldom accessed repositories.
65	The backoffice is an on-demand system.
	@@ -87,14 +89,48 @@
87	per day from random robots, which will be sufficient to kick off the
88	daily digest emails. And even for a private server, if there is very
89	little traffic, then the daily digests are probably a no-op anyhow
90	and won't be missed.
91

































92	How Backoffice Is Implemented
93	-----------------------------
94
95	The backoffice is implemented by the "backoffice.c" source file.

96
97	Serialization and rate limiting is handled by a single entry in the
98	repository database CONFIG table named "backoffice". This entry is
99	called "the lease". The value of the lease
100	is a text string representing four integers, which
101

	--- www/backoffice.md
	+++ www/backoffice.md
	@@ -55,11 +55,13 @@
55	Windows it is not possible to replace an executable file that is in active
56	use. But Windows users probably already know this.)
57
58	The backoffice is serialized and rate limited. No more than a single
59	backoffice process will be running at once, and backoffice runs will not
60	occur more frequently than once every 60 seconds. (The 60-second spacing
61	is controlled by the BKOFCE_LEASE_TIME macro in the
62	[backoffice.c](/file/src/backoffice.c) source file.)
63
64	If a Fossil server is idle, then no backoffice processes will be running.
65	That means there are no extra processes sitting around taking up memory
66	and process table slots for seldom accessed repositories.
67	The backoffice is an on-demand system.
	@@ -87,14 +89,48 @@
89	per day from random robots, which will be sufficient to kick off the
90	daily digest emails. And even for a private server, if there is very
91	little traffic, then the daily digests are probably a no-op anyhow
92	and won't be missed.
93
94	Automatic Backoffice Does Not Work On Some Systems
95	--------------------------------------------------
96
97	We have observed that the automatic backoffice does not work on
98	some system - OpenBSD in particular. We still do not understand why
99	this is. (If you have insights, please share them on the
100	[Fossil Forum](https://fossil-scm.org/forum) so that we can perhaps
101	fix the problem.) For now, the backoffice must be run manually
102	on OpenBSD systems.
103
104	To set up fully-manual backoffice, first disable the automatic backoffice
105	using the "[backoffice-disable](/help?cmd=backoffice-disable)" setting.
106
107	> fossil setting backoffice-disable on
108
109	Then arrange to invoke the backoffice separately using a command
110	like this:
111
112	> fossil backoffice --poll 30 _REPOSITORY-LIST_
113
114	Multiple repositories can be named. This one command will handle
115	launching the backoffice for all of them. There are additional useful
116	command-line options. See the "[fossil backoffice](/help?cmd=backoffice)"
117	documentation for details.
118
119	The backoffice processes run manually using the "fossil backoffice"
120	command do not normally use a lease. That means that you run the
121	"fossil backoffice" command with --poll and you forget to disable
122	automatic backoffice by setting the "backoffice-disable" flag, then
123	you might have one backoffice running due command and another due
124	to a webpage access, both at the same time. This is harmless. The
125	only downside is that it uses extra CPU time.
126
127	How Backoffice Is Implemented
128	-----------------------------
129
130	The backoffice is implemented by the
131	"[backoffice.c](/file/src/backoffice.c)" source file.
132
133	Serialization and rate limiting is handled by a single entry in the
134	repository database CONFIG table named "backoffice". This entry is
135	called "the lease". The value of the lease
136	is a text string representing four integers, which
137

Fossil SCM

Keyboard Shortcuts