[ViewVC] Annotation of: cvs/Sys-FreezeThaw/README

NAME
    Sys::FreezeThaw - stop and start all user processes on a machine

SYNOPSIS
      use Sys::FreezeThaw;

      Sys::FreezeThaw::freezethaw {
         # run code while system is frozen
      };

      my $token = Sys::FreezeThaw::freeze;
      ... do something ...
      Sys::FreezeThaw::thaw $token;

DESCRIPTION
    Operating Systems/Kernels current supported: Linux-2.6/3.0 with /proc.

    This module implements a very specific feature: stopping(freezing and
    thawing/continuing all userspace processes on the machine. It works by
    sending SIGSTOP to all processes, parent-process first, so that the wait
    syscall will not trigger on stopped children. Restarting is done in
    reverse order.

    Using the combined function Sys::FreezeThaw::freezethaw is recommended
    as it will catch runtime errors, but stopping and restarting can be dine
    via separate function calls.

  What could it possibly be sueful for??
    Possible uses include: doing atomic file system operations (such as
    replacing files while they are guaranteed not to be in use), or quieting
    down a system to investigate suspicious behaviour.

    Sys::FreezeThaw::freezethaw { BLOCK }
        First tries to stop all processes. If successful, runs the given
        code block (or code reference), then restarts all processes again.
        As the system is basically frozen during the code block execution,
        it should be as fast as possible.

        Runtime errors will be caught with "eval". If an exception occurs it
        will be re-thrown after processes are restarted. If processes cannot
        be frozen or restarted, this function will throw an exception.

        Signal handlers for SIGINT, SIGTERM, SIGPIPE, SIGHUP, SIGALRM,
        SIGUSR1 and SIGUSR2 will be installed temporarily, so if you want to
        catch these, you have to do so yourself within the executed code
        block.

        Try to do as few things as possible. For example, outputting text
        might cause a deadlock, as the terminal emulator on the other side
        of STDOUT might be stopped, logging to syslog might not work and so
        on.

        The return value of the code block is ignored right now, and the
        function doesn't yet return anything sensible.

    $token = Sys::FreezeThaw::freeze
        Send SIGSTOP to all processes, and return a token that allows them
        to be thawed again.

        If an error occurs, an exception will be thrown and all stopped
        processes will automatically be thawed.

    Sys::FreezeThaw::thaw $token
        Take a token returned by Sys::FreezeThaw::freeze and send all
        processes a "CONT" signal, in the order required for them not to
        receive child STOP notifications.

    $Sys::FreezeThaw::PARTIAL_OK
        A boolean that tells "freeze" whether it is an error if a process
        cannot be stopped. If false (the default), then "freeze" will fail
        if there is an unstoppable process. If it is true, then "freeze"
        will pretend it the process stopped.

BUGS
    SIGCONT is not unnoticed by processes. Some programs (such as
    irssi-text) respond by flickering (IMHO a bug in irssi-text). Other
    programs might have other problems, but actual problems should be rare.
    However, one shouldn't overuse this module.

AUTHOR
       Marc Lehmann <schmorp@schmorp.de>
       http://home.schmorp.de/

Revision:	1.2
Committed:	Mon Oct 7 04:21:18 2013 UTC (10 years, 8 months ago) by root
Branch:	MAIN
CVS Tags:	rel-0_02, HEAD
Changes since 1.1:	+27 -14 lines
Log Message:	0.2
#	User	Rev	Content
1	root	1.1	NAME
2			Sys::FreezeThaw - stop and start all user processes on a machine
3
4			SYNOPSIS
5			use Sys::FreezeThaw;
6
7			Sys::FreezeThaw::freezethaw {
8			# run code while system is frozen
9			};
10
11			my $token = Sys::FreezeThaw::freeze;
12			... do something ...
13			Sys::FreezeThaw::thaw $token;
14	root	1.2
15	root	1.1	DESCRIPTION
16	root	1.2	Operating Systems/Kernels current supported: Linux-2.6/3.0 with /proc.
17	root	1.1
18			This module implements a very specific feature: stopping(freezing and
19	root	1.2	thawing/continuing all userspace processes on the machine. It works by
20	root	1.1	sending SIGSTOP to all processes, parent-process first, so that the wait
21			syscall will not trigger on stopped children. Restarting is done in
22			reverse order.
23
24			Using the combined function Sys::FreezeThaw::freezethaw is recommended
25			as it will catch runtime errors, but stopping and restarting can be dine
26	root	1.2	via separate function calls.
27
28			What could it possibly be sueful for??
29			Possible uses include: doing atomic file system operations (such as
30			replacing files while they are guaranteed not to be in use), or quieting
31			down a system to investigate suspicious behaviour.
32	root	1.1
33			Sys::FreezeThaw::freezethaw { BLOCK }
34			First tries to stop all processes. If successful, runs the given
35	root	1.2	code block (or code reference), then restarts all processes again.
36			As the system is basically frozen during the code block execution,
37			it should be as fast as possible.
38	root	1.1
39			Runtime errors will be caught with "eval". If an exception occurs it
40			will be re-thrown after processes are restarted. If processes cannot
41			be frozen or restarted, this function will throw an exception.
42
43	root	1.2	Signal handlers for SIGINT, SIGTERM, SIGPIPE, SIGHUP, SIGALRM,
44			SIGUSR1 and SIGUSR2 will be installed temporarily, so if you want to
45			catch these, you have to do so yourself within the executed code
46			block.
47	root	1.1
48			Try to do as few things as possible. For example, outputting text
49			might cause a deadlock, as the terminal emulator on the other side
50	root	1.2	of STDOUT might be stopped, logging to syslog might not work and so
51			on.
52	root	1.1
53	root	1.2	The return value of the code block is ignored right now, and the
54	root	1.1	function doesn't yet return anything sensible.
55
56	root	1.2	$token = Sys::FreezeThaw::freeze
57	root	1.1	Send SIGSTOP to all processes, and return a token that allows them
58			to be thawed again.
59
60			If an error occurs, an exception will be thrown and all stopped
61			processes will automatically be thawed.
62
63			Sys::FreezeThaw::thaw $token
64			Take a token returned by Sys::FreezeThaw::freeze and send all
65	root	1.2	processes a "CONT" signal, in the order required for them not to
66	root	1.1	receive child STOP notifications.
67
68	root	1.2	$Sys::FreezeThaw::PARTIAL_OK
69			A boolean that tells "freeze" whether it is an error if a process
70			cannot be stopped. If false (the default), then "freeze" will fail
71			if there is an unstoppable process. If it is true, then "freeze"
72			will pretend it the process stopped.
73
74	root	1.1	BUGS
75			SIGCONT is not unnoticed by processes. Some programs (such as
76			irssi-text) respond by flickering (IMHO a bug in irssi-text). Other
77			programs might have other problems, but actual problems should be rare.
78			However, one shouldn't overuse this module.
79
80			AUTHOR
81			Marc Lehmann <schmorp@schmorp.de>
82			http://home.schmorp.de/
83