From: Amos Jeffries Date: Sat, 1 Nov 2014 05:04:05 +0000 (-0700) Subject: Docs: Add man(8) page for helper-mux tool X-Git-Tag: merge-candidate-3-v1~515 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=33d1abfe57d8af912b4f2f9e71584ea1436a73fe;p=thirdparty%2Fsquid.git Docs: Add man(8) page for helper-mux tool Convert the helper-mux.pl.README to inlineperl docs and generate a man(8) page using pod2man when possible. Also, shuffle the tool into a sub-directory of its own for easier build management. Also, add a automake conditional ENABLE_POD2MAN_DOC to allow optional build of perl tools or helpers without depending on pod2man which is only necessary for the documentation. --- diff --git a/configure.ac b/configure.ac index 51c6f1516b..1f1193dd5e 100644 --- a/configure.ac +++ b/configure.ac @@ -129,6 +129,7 @@ if test "x$ac_cv_path_PERL" = "xnone"; then AC_MSG_FAILURE([Perl is required to compile Squid. Please install Perl and then re-run configure ]) fi AC_PATH_PROG(POD2MAN, pod2man, $FALSE) +AM_CONDITIONAL(ENABLE_POD2MAN_DOC, test "x${ac_cv_path_POD2MAN}" != "x$FALSE") dnl set $(AR) if not provided by the build environment if test "x$AR" = "x"; then @@ -3848,6 +3849,7 @@ AC_CONFIG_FILES([ helpers/storeid_rewrite/Makefile helpers/storeid_rewrite/file/Makefile tools/Makefile + tools/helper-mux/Makefile tools/squidclient/Makefile tools/purge/Makefile ]) diff --git a/tools/Makefile.am b/tools/Makefile.am index 26917904a6..0f3fa5f00a 100644 --- a/tools/Makefile.am +++ b/tools/Makefile.am @@ -12,7 +12,7 @@ AUTOMAKE_OPTIONS = subdir-objects ## we need our local files too (but avoid -I. at all costs) AM_CPPFLAGS += -I$(srcdir) -SUBDIRS = purge squidclient +SUBDIRS = helper-mux purge squidclient EXTRA_DIST = man_MANS = DISTCLEANFILES = @@ -46,11 +46,6 @@ time.cc: $(top_srcdir)/src/time.cc TESTSOURCES= test_tools.cc CLEANFILES += test_tools.cc stub_debug.cc time.cc -## ##### helper-mux ##### - -libexec_SCRIPTS = helper-mux.pl -EXTRA_DIST += helper-mux.pl helper-mux.README - ## Test Scripts EXTRA_DIST += helper-ok-dying.pl helper-ok.pl diff --git a/tools/helper-mux.README b/tools/helper-mux.README deleted file mode 100644 index b1a426bc44..0000000000 --- a/tools/helper-mux.README +++ /dev/null @@ -1,16 +0,0 @@ -The helper multiplexer's purpose is to relieve some of the burden -squid has when dealing with slow helpers. It does so by acting as a -middleman between squid and the actual helpers, talking to squid via -the multiplexed variant of the helper protocol and to the helpers -via the non-multiplexed variant. - -Helpers are started on demand, and in theory the muxer can handle up to -1k helpers per instance. It's up to squid to decide how many helpers -to start. - -The muxer knows nothing about the actual messages being passed around, -and as such can't really (yet?) compensate for broken helpers. -It is not yet able to manage dying helpers, but it will. - -The helper can be controlled using various signals: -- SIGHUP: dump the state of all helpers to STDERR diff --git a/tools/helper-mux/Makefile.am b/tools/helper-mux/Makefile.am new file mode 100644 index 0000000000..2f88553419 --- /dev/null +++ b/tools/helper-mux/Makefile.am @@ -0,0 +1,24 @@ +## Copyright (C) 1996-2014 The Squid Software Foundation and contributors +## +## Squid software is distributed under GPLv2+ license and includes +## contributions from numerous individuals and organizations. +## Please see the COPYING and CONTRIBUTORS files for details. + +include $(top_srcdir)/src/Common.am + +libexec_SCRIPTS = helper-mux +CLEANFILES += helper-mux +EXTRA_DIST= helper-mux.pl.in + +if ENABLE_POD2MAN_DOC +man_MANS = helper-mux.8 +CLEANFILES += helper-mux.8 +EXTRA_DIST += helper-mux.8 + +helper-mux.8: helper-mux + pod2man helper-mux helper-mux.8 + +endif + +helper-mux: helper-mux.pl.in + $(subst_perlshell) diff --git a/tools/helper-mux.pl b/tools/helper-mux/helper-mux.pl.in similarity index 65% rename from tools/helper-mux.pl rename to tools/helper-mux/helper-mux.pl.in index 18028f67b5..ea79032a1a 100755 --- a/tools/helper-mux.pl +++ b/tools/helper-mux/helper-mux.pl.in @@ -1,37 +1,82 @@ -#!/usr/bin/perl -# -## Copyright (C) 1996-2014 The Squid Software Foundation and contributors -## -## Squid software is distributed under GPLv2+ license and includes -## contributions from numerous individuals and organizations. -## Please see the COPYING and CONTRIBUTORS files for details. -## -# -# helper multiplexer. Talks to squid using the multiplexed variant of -# the helper protocol, and maintains a farm of synchronous helpers -# helpers are lazily started, as many as needed. -# see helper-mux.README for further informations -# -# AUTHOR: Francesco Chemolli -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program 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 General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA. +#!@PERL@ use Getopt::Std; use Data::Dumper; use FileHandle; use IPC::Open2; +use Pod::Usage; + +=pod + +=head1 NAME + +helper-mux - Concurrency protocol multiplexer for Squid helpers + +=head1 SYNOPSIS + +B helper-path [helper-options ...] + +=head1 DESCRIPTION + +B purpose is to relieve some of the burden +B has when dealing with slow helpers. It does so by acting as a +middleman between B and the actual helpers, talking to B via +the multiplexed variant of the helper protocol and to the helpers +via the non-multiplexed variant. + +Helpers are started on demand, and in theory the muxer can handle up to +1k helpers per instance. It is up to B to decide how many helpers +to start. + +The helper can be controlled using various signals: +- SIGHUP: dump the state of all helpers to STDERR + +=head1 OPTIONS + +=over 8 + +=item B + +Path to the helper being multiplexed. + +=item B + +Command line options for the helper being multiplexed. + +=back + +=head1 KNOWN ISSUES + +B knows nothing about the actual messages being passed around, +and as such cannot yet compensate for broken helpers. + +It is not yet able to manage dying helpers. + +=head1 COPYRIGHT + + * Copyright (C) 1996-2014 The Squid Software Foundation and contributors + * + * Squid software is distributed under GPLv2+ license and includes + * contributions from numerous individuals and organizations. + * Please see the COPYING and CONTRIBUTORS files for details. + + Copyright (C) Francesco Chemolli + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program 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 General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA. + +=cut #mux-ed format: "slot_num non_muxed_request"