3:20 p.m.
From: "Richard W.M. Jones" <rjones(a)redhat.com>
These limit the number of concurrent handles which can be used
at once.
---
fish/guestfish.pod | 8 ++
generator/actions.ml | 87 +++++++++++++++++
generator/events.ml | 4 +
ocaml/t/guestfs_400_events.ml | 5 +-
po/POTFILES | 1 +
src/Makefile.am | 1 +
src/guestfs-internal.h | 11 +++
src/guestfs.pod | 120 ++++++++++++++++++++++++
src/handle.c | 20 +++-
src/launch.c | 4 +
src/mutex.c | 213 ++++++++++++++++++++++++++++++++++++++++++
src/proto.c | 1 +
test-tool/test-tool.c | 3 +
13 files changed, 476 insertions(+), 2 deletions(-)
create mode 100644 src/mutex.c
diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index 5fec2f2..28dde6c 100644
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -1279,6 +1279,14 @@ example:
LIBGUESTFS_MEMSIZE=700
+=item LIBGUESTFS_MUTEX_FILE
+
+=item LIBGUESTFS_MUTEX_LIMIT
+
+Set these in order to limit the number of concurrent guestfish
+sessions launched at once. See L<guestfs(3)/MUTEX> and
+L</set-mutex-limit>.
+
=item LIBGUESTFS_PATH
Set the path that guestfish uses to search for kernel and initrd.img.
diff --git a/generator/actions.ml b/generator/actions.ml
index 4f18f41..d664a7a 100644
--- a/generator/actions.ml
+++ b/generator/actions.ml
@@ -2694,6 +2694,93 @@ the default. Else C</var/tmp> is the default." };
longdesc = "\
Get the directory used by the handle to store the appliance cache." };
+ { defaults with
+ name = "set_mutex_file";
+ style = RErr, [OptString "mutexfile"], [];
+ config_only = true; blocking = false;
+ shortdesc = "set mutex filename to limit concurrent handles";
+ longdesc = "\
+Set the name of the semaphore file used to limit concurrent handles.
+The name must start with a C</> character, and contain no other
+C</> characters (eg. C</guestfs.mutex>). See L<sem_overview(7)>
+for an explanation.
+
+See L<guestfs(3)/MUTEX>." };
+
+ { defaults with
+ name = "get_mutex_file";
+ style = RConstOptString "mutexfile", [], [];
+ blocking = false;
+ shortdesc = "get mutex filename";
+ longdesc = "\
+Get the name of the semaphore file.
+
+See C<guestfs_set_mutex_file> and L<guestfs(3)/MUTEX>." };
+
+ { defaults with
+ name = "set_mutex_limit";
+ style = RErr, [Int "limit"], [];
+ config_only = true; blocking = false;
+ shortdesc = "set mutex to limit concurrent handles";
+ longdesc = "\
+This sets the limit of the number of concurrent handles that
+may be launched at the same time. The intention is to limit
+the overall load that libguestfs places on the host.
+
+Note that in the current implementation which uses a POSIX
+semaphore, you have to delete the semaphore file (or reboot the
+host) in order to change this limit. See L<sem_overview(7)> for
+the location of the semaphore file. This may be fixed in future.
+
+As well as ordinary positive integers, meaning to limit
+the number of launched handles to C<limit>, various magic
+values are possible too:
+
+=over 4
+
+=item C<limit> E<ge> 1
+
+Limit the number of launched handles to at most C<limit> concurrently.
+
+=item C<0>
+
+Disable limits.
+
+=item C<-2>
+
+Let libguestfs choose a suitable limit based on the free memory
+available on the host when the semaphore is first created.
+
+If there is less memory available than libguestfs thinks is necessary,
+libguestfs will still allow one handle to run (otherwise that handle
+would be waiting forever).
+
+This is probably the best choice for most users.
+
+=item C<limit> E<le> -128
+
+Calculate the maximum number of concurrent handles by dividing
+the free memory by C<-limit>. This calculation is done when the
+semaphore is first created.
+
+Libguestfs will always allow at least one handle to run
+(otherwise that handle would be waiting forever).
+
+=back
+
+For more information see L<guestfs(3)/MUTEX>." };
+
+ { defaults with
+ name = "get_mutex_limit";
+ style = RInt "limit", [], [];
+ blocking = false;
+ shortdesc = "get mutex limit";
+ longdesc = "\
+This returns the mutex limit. If not previously set, the
+default is C<0> (meaning the mutex feature is disabled).
+
+See C<guestfs_set_mutex_limit> and L<guestfs(3)/MUTEX>." };
+
]
(* daemon_functions are any functions which cause some action
diff --git a/generator/events.ml b/generator/events.ml
index 58c0c54..9c69705 100644
--- a/generator/events.ml
+++ b/generator/events.ml
@@ -39,6 +39,10 @@ let events = [
"enter"; (* enter a function *)
"libvirt_auth"; (* libvirt authentication request *)
+
+ "mutex_blocked"; (* mutex events *)
+ "mutex_entered";
+ "mutex_released";
]
let events = mapi (fun i name -> name, 1 lsl i) events
diff --git a/ocaml/t/guestfs_400_events.ml b/ocaml/t/guestfs_400_events.ml
index be40608..76d27a5 100644
--- a/ocaml/t/guestfs_400_events.ml
+++ b/ocaml/t/guestfs_400_events.ml
@@ -29,7 +29,10 @@ let log g ev eh buf array =
| Guestfs.EVENT_LIBRARY -> "library"
| Guestfs.EVENT_TRACE -> "trace"
| Guestfs.EVENT_ENTER -> "enter"
- | Guestfs.EVENT_LIBVIRT_AUTH -> "libvirt_auth" in
+ | Guestfs.EVENT_LIBVIRT_AUTH -> "libvirt_auth"
+ | Guestfs.EVENT_MUTEX_BLOCKED -> "mutex_blocked"
+ | Guestfs.EVENT_MUTEX_ENTERED -> "mutex_entered"
+ | Guestfs.EVENT_MUTEX_RELEASED -> "mutex_released" in
let eh : int = Obj.magic eh in
diff --git a/po/POTFILES b/po/POTFILES
index 0686966..e3430f2 100644
--- a/po/POTFILES
+++ b/po/POTFILES
@@ -263,6 +263,7 @@ src/libvirt-domain.c
src/listfs.c
src/lpj.c
src/match.c
+src/mutex.c
src/osinfo.c
src/private-data.c
src/proto.c
diff --git a/src/Makefile.am b/src/Makefile.am
index 2c3af05..3410803 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -171,6 +171,7 @@ libguestfs_la_SOURCES = \
listfs.c \
lpj.c \
match.c \
+ mutex.c \
osinfo.c \
private-data.c \
proto.c \
diff --git a/src/guestfs-internal.h b/src/guestfs-internal.h
index 48ab745..00c029e 100644
--- a/src/guestfs-internal.h
+++ b/src/guestfs-internal.h
@@ -23,6 +23,8 @@
#include <libintl.h>
+#include <semaphore.h>
+
#include <rpc/types.h>
#include <rpc/xdr.h>
@@ -292,6 +294,11 @@ struct guestfs_h
virConnectCredentialPtr requested_credentials;
#endif
+ /* Used by the handle mutex (see src/mutex.c). */
+ char *mutex_file;
+ int mutex_limit;
+ sem_t *semaphore;
+
/**** Private data for attach-methods. ****/
/* NB: This cannot be a union because of a pathological case where
* the user changes attach-method while reusing the handle to launch
@@ -519,6 +526,10 @@ extern char *guestfs___appliance_command_line (guestfs_h *g, const
char *applian
/* launch-appliance.c */
extern char *guestfs___drive_name (size_t index, char *ret);
+/* mutex.c */
+extern int guestfs___acquire_mutex (guestfs_h *g);
+extern void guestfs___release_mutex (guestfs_h *g);
+
/* inspect.c */
extern void guestfs___free_inspect_info (guestfs_h *g);
extern int guestfs___feature_available (guestfs_h *g, const char *feature);
diff --git a/src/guestfs.pod b/src/guestfs.pod
index d21ac8c..bec1249 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -718,6 +718,100 @@ available from the L</guestfs_inspect_is_live>,
L</guestfs_inspect_is_netinst> and L</guestfs_inspect_is_multipart>
calls.
+=head2 MUTEX
+
+You can limit the number of launched handles (per host) to avoid
+having too many libguestfs instances running at once. This is known
+as the handle "mutex". This works by having a shared semaphore. If
+the limit is reached, handles wait on this semaphore until other
+instances finish.
+
+The default is no lock file and no limit on the number of concurrent
+handles.
+
+=head3 SETTING THE MUTEX LOCK FILE AND LIMIT
+
+To use this feature, after you open each handle but before calling
+L</guestfs_launch>, set the semaphore filename and limit by calling
+L</guestfs_set_mutex_file> and L</guestfs_set_mutex_limit>.
+
+The semaphore filename is a special type of filename that starts with
+a C</> character and contains no other C</> characters
+(eg. C</guestfs.mutex>). See L<sem_overview(7)> for an explanation.
+
+The same filename should be passed to every handle.
+
+The limit is simply an integer (the number of handles). The limit can
+have various magic values too, read the documentation for
+L</guestfs_set_mutex_limit>.
+
+Alternatively, ensure that the following environment variables are set
+globally for every libguestfs user / process: C<LIBGUESTFS_MUTEX_FILE>
+and C<LIBGUESTFS_MUTEX_LIMIT>.
+
+The example below shows how to use the environment variables. The
+special limit of C<-2> causes libguestfs to choose a suitable limit
+based on the amount of free memory on the host:
+
+ LIBGUESTFS_MUTEX_FILE=/guestfs.mutex
+ LIBGUESTFS_MUTEX_LIMIT=-2
+ export LIBGUESTFS_MUTEX_FILE LIBGUESTFS_MUTEX_LIMIT
+
+=head3 MUTEX CHANGES TO LAUNCH AND CLOSE
+
+When the mutex has been configured, L</guestfs_launch> may block if
+there are too many other handles running at the same time. Similarly,
+L</guestfs_shutdown> or L</guestfs_close> may release the lock causing
+another handle that was waiting to start launching.
+
+You can see if handles are blocked by enabling debugging or by
+registering for events (see next section).
+
+=head3 MUTEX EVENTS
+
+The API allows callers to receive an event when a handle is blocked
+acquiring the lock, has acquired the lock, or has released the lock.
+Events only let you monitor this; they don't let you change the mutex
+behaviour on the fly.
+
+The three events are C<GUESTFS_EVENT_MUTEX_BLOCKED> (blocked when
+trying to acquire the mutex), C<GUESTFS_EVENT_MUTEX_ENTERED>
+(successfully acquired the mutex), and C<GUESTFS_EVENT_MUTEX_RELEASED>
+(have just released the mutex). All events have a string payload
+which is the name of the semaphore file (ie. the same string passed to
+L</guestfs_set_mutex_file>).
+
+Note that the C<BLOCKED> event is only generated if the handle
+actually waits, not if the handle goes straight into the mutex.
+
+If mutexes are not configured, then none of these events will be
+generated.
+
+For further information about events, see L</EVENTS>.
+
+=head3 MUTEX IMPLEMENTATION NOTES
+
+Currently the mutex is implemented using POSIX semaphores (this
+implementation detail may change in future).
+
+The mutex is only enabled if the mutex semaphore file is set and the
+limit is set to a non-zero value.
+
+The mutex only affects when handles can be launched. You can still
+create as many handles as you like, which should be safe because
+handles that are not launched just use a little memory in the current
+process.
+
+The mutex must be enabled on all handles. If you don't enable it on a
+particular handle, then that handle will ignore the mutex (even if it
+is set on other handles).
+
+Currently, if you want to change the limit then you have to delete the
+semaphore file.
+
+For the magic negative values of the limit, libguestfs uses the output
+of the L<free(1)> command to determine free memory on the host.
+
=head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
Libguestfs can mount NTFS partitions. It does this using the
@@ -2486,6 +2580,24 @@ authentication information. See L</LIBVIRT AUTHENTICATION>
below.
If no callback is registered: C<virConnectAuthPtrDefault> is
used (suitable for command-line programs only).
+=item GUESTFS_EVENT_MUTEX_BLOCKED
+(payload type: lock file name)
+
+During launch, the handle is blocked waiting for the mutex.
+See L</MUTEX>.
+
+=item GUESTFS_EVENT_MUTEX_ENTERED
+(payload type: lock file name)
+
+During launch, the handle acquired the mutex lock.
+See L</MUTEX>.
+
+=item GUESTFS_EVENT_MUTEX_RELEASED
+(payload type: lock file name)
+
+During shutdown, the handle released the mutex lock.
+See L</MUTEX>.
+
=back
=head2 EVENT API
@@ -4131,6 +4243,14 @@ example:
LIBGUESTFS_MEMSIZE=700
+=item LIBGUESTFS_MUTEX_FILE
+
+=item LIBGUESTFS_MUTEX_LIMIT
+
+Set these in order to limit the number of concurrent libguestfs
+handles running at once. See L</MUTEX> and
+L</guestfs_set_mutex_limit>.
+
=item LIBGUESTFS_PATH
Set the path that libguestfs uses to search for a supermin appliance.
diff --git a/src/handle.c b/src/handle.c
index c630daf..6c9b311 100644
--- a/src/handle.c
+++ b/src/handle.c
@@ -144,6 +144,7 @@ guestfs_create_flags (unsigned flags, ...)
return g;
error:
+ free (g->mutex_file);
free (g->attach_method_arg);
free (g->path);
free (g->qemu);
@@ -157,7 +158,7 @@ parse_environment (guestfs_h *g,
char *(*do_getenv) (const void *data, const char *),
const void *data)
{
- int memsize;
+ int memsize, limit;
char *str;
/* Don't bother checking the return values of functions
@@ -215,6 +216,20 @@ parse_environment (guestfs_h *g,
return -1;
}
+ str = do_getenv (data, "LIBGUESTFS_MUTEX_FILE");
+ if (str)
+ guestfs_set_mutex_file (g, str);
+
+ str = do_getenv (data, "LIBGUESTFS_MUTEX_LIMIT");
+ if (str) {
+ if (sscanf (str, "%d", &limit) != 1) {
+ error (g, _("non-numeric value for LIBGUESTFS_MUTEX_LIMIT"));
+ return -1;
+ }
+ if (guestfs_set_mutex_limit (g, limit) == -1)
+ return -1;
+ }
+
return 0;
}
@@ -326,6 +341,7 @@ guestfs_close (guestfs_h *g)
if (g->pda)
hash_free (g->pda);
+ free (g->mutex_file);
free (g->tmpdir);
free (g->env_tmpdir);
free (g->int_tmpdir);
@@ -378,6 +394,8 @@ shutdown_backend (guestfs_h *g, int check_for_errors)
if (g->attach_ops->shutdown (g, check_for_errors) == -1)
ret = -1;
+ guestfs___release_mutex (g);
+
guestfs___free_drives (g);
g->state = CONFIG;
diff --git a/src/launch.c b/src/launch.c
index 7c37667..0401c42 100644
--- a/src/launch.c
+++ b/src/launch.c
@@ -597,6 +597,10 @@ guestfs__launch (guestfs_h *g)
return -1;
}
+ /* Acquire mutex if we need to. */
+ if (guestfs___acquire_mutex (g) == -1)
+ return -1;
+
/* Start the clock ... */
gettimeofday (&g->launch_t, NULL);
TRACE0 (launch_start);
diff --git a/src/mutex.c b/src/mutex.c
new file mode 100644
index 0000000..82efc9b
--- /dev/null
+++ b/src/mutex.c
@@ -0,0 +1,213 @@
+/* libguestfs
+ * Copyright (C) 2013 Red Hat Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#include <config.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+#include <fcntl.h>
+#include <sys/stat.h>
+#include <semaphore.h>
+#include <errno.h>
+
+#include "guestfs.h"
+#include "guestfs-internal.h"
+#include "guestfs-internal-actions.h"
+#include "guestfs_protocol.h"
+
+int
+guestfs__set_mutex_file (guestfs_h *g, const char *file)
+{
+ free (g->mutex_file);
+ g->mutex_file = NULL;
+
+ if (file)
+ g->mutex_file = safe_strdup (g, file);
+
+ return 0;
+}
+
+const char *
+guestfs__get_mutex_file (guestfs_h *g)
+{
+ return g->mutex_file;
+}
+
+int
+guestfs__set_mutex_limit (guestfs_h *g, int limit)
+{
+ if (limit > 1000) { /* that would be > 1000 concurrent handles */
+ error (g, _("mutex limit is too large. If you want it to be unlimited set it to
0. If you want a larger-but-finite limit then you have to recompile libguestfs."));
+ return -1;
+ }
+ if (limit == -1) {
+ error (g, _("mutex limit cannot be set to -1 (did you mean -2?)"));
+ return -1;
+ }
+ if (limit >= -127 && limit <= -3) {
+ error (g, _("mutex limit cannot be set to -3..-127"));
+ return -1;
+ }
+ if (limit < -10000) { /* that would be a > 10 GB process limit */
+ error (g, _("mutex limit is too small"));
+ return -1;
+ }
+
+ g->mutex_limit = limit;
+ return 0;
+}
+
+int
+guestfs__get_mutex_limit (guestfs_h *g)
+{
+ return g->mutex_limit;
+}
+
+static int
+mutex_is_enabled (guestfs_h *g)
+{
+ return g->mutex_file != NULL && g->mutex_limit != 0;
+}
+
+static void
+read_free_memory (guestfs_h *g, void *datav, const char *line, size_t len)
+{
+ int *mbytesp = (int *) datav;
+
+ if (sscanf (line, "%d", mbytesp) == -1)
+ *mbytesp = -1;
+}
+
+static int
+get_free_memory (guestfs_h *g)
+{
+ CLEANUP_CMD_CLOSE struct command *cmd = guestfs___new_command (g);
+ int r, mbytes = -1;
+
+ guestfs___cmd_add_string_unquoted (cmd, "free -m | "
+ "grep 'buffers/cache' | "
+ "awk '{print $NF}'");
+ guestfs___cmd_set_stdout_callback (cmd, read_free_memory, &mbytes, 0);
+ r = guestfs___cmd_run (cmd);
+ if (r == -1)
+ return -1;
+ if (!WIFEXITED (r) || WEXITSTATUS (r) != 0) {
+ error (g, _("failed when trying to read free memory"));
+ return -1;
+ }
+
+ if (mbytes == -1) {
+ error (g, _("unexpected output from 'free -m' command"));
+ return -1;
+ }
+
+ debug (g, "get_free_memory: %d MB free", mbytes);
+
+ return mbytes;
+}
+
+static int
+get_initial_value (guestfs_h *g)
+{
+ int free_mbytes;
+
+ if (g->mutex_limit >= 1)
+ return g->mutex_limit;
+
+ free_mbytes = get_free_memory (g);
+ if (free_mbytes == -1)
+ return -1;
+
+ if (g->mutex_limit == -2) {
+ /* This is an overestimate ... */
+ int estimate_size_per_appliance = DEFAULT_MEMSIZE + 350;
+ return MAX (1, free_mbytes / estimate_size_per_appliance);
+ }
+
+ return MAX (1, free_mbytes / -g->mutex_limit);
+}
+
+/* This is called very early in 'launch' to acquire the mutex. */
+int
+guestfs___acquire_mutex (guestfs_h *g)
+{
+ sem_t *semaphore;
+ int v;
+
+ if (!mutex_is_enabled (g))
+ return 0;
+
+ v = get_initial_value (g);
+ if (v == -1)
+ return -1;
+
+ debug (g, "mutex: initializing semaphore %s with value %d (note that if the
semaphore exists already, then this value is ignored)", g->mutex_file, v);
+
+ /* XXX umask */
+ semaphore = sem_open (g->mutex_file, O_CREAT|O_CLOEXEC, 0777, (unsigned) v);
+ if (semaphore == SEM_FAILED) {
+ perrorf (g, _("mutex: sem_open: %s"), g->mutex_file);
+ return -1;
+ }
+
+ if (sem_trywait (semaphore) == -1) {
+ if (errno == EAGAIN) {
+ debug (g, _("mutex: blocked waiting for semaphore %s "
+ "(see \"MUTEX\" in guestfs(3))"),
+ g->mutex_file);
+
+ guestfs___call_callbacks_message (g, GUESTFS_EVENT_MUTEX_BLOCKED,
+ g->mutex_file, strlen (g->mutex_file));
+
+ if (sem_wait (semaphore) == -1)
+ goto error;
+ }
+ else {
+ error:
+ perrorf (g, _("mutex: sem_wait: %s"), g->mutex_file);
+ sem_close (semaphore);
+ return -1;
+ }
+ }
+
+ g->semaphore = semaphore;
+
+ guestfs___call_callbacks_message (g, GUESTFS_EVENT_MUTEX_ENTERED,
+ g->mutex_file, strlen (g->mutex_file));
+
+ return 0;
+}
+
+/* This is called late in 'shutdown' to release the mutex. */
+void
+guestfs___release_mutex (guestfs_h *g)
+{
+ if (!g->semaphore)
+ return;
+
+ if (sem_post (g->semaphore) == -1)
+ debug (g, "sem_post: %s", g->mutex_file);
+ if (sem_close (g->semaphore) == -1)
+ debug (g, "sem_close: %s", g->mutex_file);
+ g->semaphore = NULL;
+
+ guestfs___call_callbacks_message (g, GUESTFS_EVENT_MUTEX_RELEASED,
+ g->mutex_file, strlen (g->mutex_file));
+}
diff --git a/src/proto.c b/src/proto.c
index 2e3b480..f909f6e 100644
--- a/src/proto.c
+++ b/src/proto.c
@@ -168,6 +168,7 @@ child_cleanup (guestfs_h *g)
g->fd[1] = -1;
g->sock = -1;
memset (&g->launch_t, 0, sizeof g->launch_t);
+ guestfs___release_mutex (g);
guestfs___free_drives (g);
g->state = CONFIG;
guestfs___call_callbacks_void (g, GUESTFS_EVENT_SUBPROCESS_QUIT);
diff --git a/test-tool/test-tool.c b/test-tool/test-tool.c
index d71caed..621f625 100644
--- a/test-tool/test-tool.c
+++ b/test-tool/test-tool.c
@@ -248,6 +248,9 @@ main (int argc, char *argv[])
free (p);
printf ("guestfs_get_direct: %d\n", guestfs_get_direct (g));
printf ("guestfs_get_memsize: %d\n", guestfs_get_memsize (g));
+ printf ("guestfs_get_mutex_file: %s\n",
+ guestfs_get_mutex_file (g) ? : "(null)");
+ printf ("guestfs_get_mutex_limit: %d\n", guestfs_get_mutex_limit (g));
printf ("guestfs_get_network: %d\n", guestfs_get_network (g));
printf ("guestfs_get_path: %s\n", guestfs_get_path (g) ? :
"(null)");
printf ("guestfs_get_pgroup: %d\n", guestfs_get_pgroup (g));
--
1.8.1.2