[thirdparty/git.git] / Documentation / technical / api-sigchain.txt

sigchain API
============

Code often wants to set a signal handler to clean up temporary files or
other work-in-progress when we die unexpectedly. For multiple pieces of
code to do this without conflicting, each piece of code must remember
the old value of the handler and restore it either when:

  1. The work-in-progress is finished, and the handler is no longer
     necessary. The handler should revert to the original behavior
     (either another handler, SIG_DFL, or SIG_IGN).

  2. The signal is received. We should then do our cleanup, then chain
     to the next handler (or die if it is SIG_DFL).

Sigchain is a tiny library for keeping a stack of handlers. Your handler
and installation code should look something like:

------------------------------------------
  void clean_foo_on_signal(int sig)
  {
	  clean_foo();
	  sigchain_pop(sig);
	  raise(sig);
  }

  void other_func()
  {
	  sigchain_push_common(clean_foo_on_signal);
	  mess_up_foo();
	  clean_foo();
  }
------------------------------------------

Handlers are given the typedef of sigchain_fun. This is the same type
that is given to signal() or sigaction(). It is perfectly reasonable to
push SIG_DFL or SIG_IGN onto the stack.

You can sigchain_push and sigchain_pop individual signals. For
convenience, sigchain_push_common will push the handler onto the stack
for many common signals.
Commit	Line	Data
ed296fe8 JK	1	sigchain API
	2	============
	3
	4	Code often wants to set a signal handler to clean up temporary files or
	5	other work-in-progress when we die unexpectedly. For multiple pieces of
	6	code to do this without conflicting, each piece of code must remember
	7	the old value of the handler and restore it either when:
	8
	9	1. The work-in-progress is finished, and the handler is no longer
	10	necessary. The handler should revert to the original behavior
	11	(either another handler, SIG_DFL, or SIG_IGN).
	12
	13	2. The signal is received. We should then do our cleanup, then chain
	14	to the next handler (or die if it is SIG_DFL).
	15
	16	Sigchain is a tiny library for keeping a stack of handlers. Your handler
	17	and installation code should look something like:
	18
	19	------------------------------------------
	20	void clean_foo_on_signal(int sig)
	21	{
	22	clean_foo();
	23	sigchain_pop(sig);
	24	raise(sig);
	25	}
	26
	27	void other_func()
	28	{
	29	sigchain_push_common(clean_foo_on_signal);
	30	mess_up_foo();
	31	clean_foo();
	32	}
	33	------------------------------------------
	34
469bfc96	35	Handlers are given the typedef of sigchain_fun. This is the same type
ed296fe8 JK	36	that is given to signal() or sigaction(). It is perfectly reasonable to
	37	push SIG_DFL or SIG_IGN onto the stack.
	38
	39	You can sigchain_push and sigchain_pop individual signals. For
	40	convenience, sigchain_push_common will push the handler onto the stack
	41	for many common signals.