E-MailRelay
gcleanup.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2024 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gcleanup.h
19///
20
21#ifndef G_CLEANUP_H
22#define G_CLEANUP_H
23
24#include "gdef.h"
25#include "gpath.h"
26#include "gsignalsafe.h"
27#include "gexception.h"
28
29namespace G
30{
31 class Cleanup ;
32 class CleanupImp ;
33}
34
35//| \class G::Cleanup
36/// A static interface for registering cleanup functions that are called when
37/// the process terminates abnormally. On unix this relates to signals like
38/// SIGTERM, SIGINT etc.
39///
41{
42public:
43 G_EXCEPTION( Error , tx("cleanup error") )
44 struct Block /// A RAII class to temporarily block signal delivery.
45 {
46 explicit Block( bool active = true ) noexcept ;
47 ~Block() ;
48 bool m_active ;
49 Block( const Block & ) = delete ;
50 Block( Block && ) = delete ;
51 Block & operator=( const Block & ) = delete ;
52 Block & operator=( Block && ) = delete ;
53 } ;
54 struct Arg /// Opaque leaky string pointer wrapper created by G::Cleanup::arg().
55 {
56 const char * str() const noexcept ;
57 bool isPath() const noexcept ;
58 private:
59 friend class G::CleanupImp ;
60 const char * m_ptr {nullptr} ;
61 bool m_is_path {false} ;
62 } ;
63 using Fn = bool (*)(const Arg &) GDEF_FSIG_NOEXCEPT ; // noexcept if c++17
64
65 static void init() ;
66 ///< An optional early-initialisation function. May be called more than once.
67
68 static void add( Fn , Arg arg ) ;
69 ///< Adds the given handler to the list of handlers that are to be called
70 ///< when the process terminates abnormally. In principle the handler
71 ///< function should be fully reentrant and signal-safe.
72 ///<
73 ///< The 'arg' value should come from arg(). The Arg object contains a
74 ///< copy of the data passed to it. It uses memory allocated on the heap
75 ///< which is never freed because it has to remain valid even as the
76 ///< process is terminating.
77 ///<
78 ///< Once the handler returns true it is removed from the list of
79 ///< handlers; if it returns false then it may be retried.
80
81 static void atexit( bool active = true ) ;
82 ///< Ensures that the cleanup functions are also called via atexit(), in
83 ///< addition to abnormal-termination signals.
84 ///<
85 ///< This can be useful when ancient third-party library code (eg. Xlib)
86 ///< might call exit(), but be careful to disable these exit handlers
87 ///< before normal termination by calling atexit(false).
88
89 static void block() noexcept ;
90 ///< Temporarily blocks signals until release()d. This should be used
91 ///< before creating threads so that only the main thread does signal
92 ///< handling.
93
94 static void release() noexcept ;
95 ///< Releases block()ed signals.
96
97 static Arg arg( const char * ) ;
98 ///< Duplicates a c-string for add(). The duped pointer will be passed
99 ///< to the handler.
100
101 static Arg arg( const std::string & ) ;
102 ///< Duplicates a string for add(). The duplicate's data() pointer will
103 ///< be passed to the handler.
104
105 static Arg arg( const Path & ) ;
106 ///< Duplicates a path for add(). The path's string pointer will be
107 ///< passed to the handler.
108
109 static Arg arg( std::nullptr_t ) ;
110 ///< Duplicates an empty string for add().
111
112public:
113 Cleanup() = delete ;
114} ;
115
116inline
117G::Cleanup::Block::Block( bool active ) noexcept :
118 m_active(active)
119{
120 if( m_active )
122}
123
124inline
125G::Cleanup::Block::~Block()
126{
127 if( m_active )
129}
130
131#endif
A static interface for registering cleanup functions that are called when the process terminates abno...
Definition: gcleanup.h:41
static Arg arg(const char *)
Duplicates a c-string for add().
static void atexit(bool active=true)
Ensures that the cleanup functions are also called via atexit(), in addition to abnormal-termination ...
static void release() noexcept
Releases block()ed signals.
static void block() noexcept
Temporarily blocks signals until release()d.
static void init()
An optional early-initialisation function. May be called more than once.
static void add(Fn, Arg arg)
Adds the given handler to the list of handlers that are to be called when the process terminates abno...
A Path object represents a file system path.
Definition: gpath.h:82
Low-level classes.
Definition: garg.h:36
constexpr const char * tx(const char *p) noexcept
A briefer alternative to G::gettext_noop().
Definition: ggettext.h:84
STL namespace.
Opaque leaky string pointer wrapper created by G::Cleanup::arg().
Definition: gcleanup.h:55
A RAII class to temporarily block signal delivery.
Definition: gcleanup.h:45