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
29 namespace 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///
40 class G::Cleanup
41{
42 public:
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
117 G::Cleanup::Block::Block( bool active ) noexcept :
118 m_active(active)
119{
120 if( m_active )
121 Cleanup::block() ;
122}
123
124 inline
125G::Cleanup::Block::~Block()
126{
127 if( m_active )
128 Cleanup::release() ;
129}
130
131#endif
G::Cleanup
A static interface for registering cleanup functions that are called when the process terminates abno...
Definition: gcleanup.h:41
G::Cleanup::arg
static Arg arg(const char *)
Duplicates a c-string for add().
Definition: gcleanup_unix.cpp:117
G::Cleanup::atexit
static void atexit(bool active=true)
Ensures that the cleanup functions are also called via atexit(), in addition to abnormal-termination ...
Definition: gcleanup_unix.cpp:100
G::Cleanup::release
static void release() noexcept
Releases block()ed signals.
Definition: gcleanup_unix.cpp:111
G::Cleanup::block
static void block() noexcept
Temporarily blocks signals until release()d.
Definition: gcleanup_unix.cpp:106
G::Cleanup::init
static void init()
An optional early-initialisation function. May be called more than once.
Definition: gcleanup_unix.cpp:89
G::Cleanup::add
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...
Definition: gcleanup_unix.cpp:94
G::Path
A Path object represents a file system path.
Definition: gpath.h:82
gexception.h
gpath.h
gsignalsafe.h
G
Low-level classes.
Definition: garg.h:36
G::tx
constexpr const char * tx(const char *p) noexcept
A briefer alternative to G::gettext_noop().
Definition: ggettext.h:84
std
STL namespace.
G::Cleanup::Arg
Opaque leaky string pointer wrapper created by G::Cleanup::arg().
Definition: gcleanup.h:55
G::Cleanup::Block
A RAII class to temporarily block signal delivery.
Definition: gcleanup.h:45