Mercurial > molko

annotate libcore/core/panic.h @ 193:78774cc2cc6b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: minimal typo
author David Demelier <markand@malikania.fr>
date Sat, 07 Nov 2020 19:26:51 +0100
parents 789b23e01f52
children dd7c8d4321a3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
88
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 /*
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 * panic.h -- unrecoverable error handling
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 *
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 * Copyright (c) 2020 David Demelier <markand@malikania.fr>
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 *
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 * Permission to use, copy, modify, and/or distribute this software for any
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 * purpose with or without fee is hereby granted, provided that the above
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 * copyright notice and this permission notice appear in all copies.
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 *
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 */
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
18
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 #ifndef MOLKO_PANIC_H
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 #define MOLKO_PANIC_H
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
21
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 /**
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
23 * \file panic.h
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 * \brief Unrecoverable error handling.
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 * \ingroup basics
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
26 *
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 * This set of functions should be used to detect runtime errors that are
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
28 * unexpected. They should be used only when the game cannot continue because
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
29 * it is in a unrecoverable state.
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 *
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 * Examples of appropriate use cases:
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
32 *
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 * - Game saved data is corrupt,
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
34 * - Assets are missing,
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 * - No more memory.
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
36 *
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
37 * In other contexts, use asserts to indicates programming error and
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
38 * appropriate solutions to recover the game otherwise.
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 */
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
40
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 #include <stdarg.h>
95
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
42 #include <stdnoreturn.h>
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
43
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
44 #include "plat.h"
88
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
45
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 /**
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 * \brief Global panic handler.
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 *
95
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
49 * The default implementation shows the last error and exit with code 1. The
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
50 * function must not return so you have to implement a setjmp/longjmp or a
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
51 * exception to be thrown.
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
52 *
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
53 * If the user defined function returns, panic routines will finally exit with
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
54 * code 1.
88
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 */
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 extern void (*panic_handler)(void);
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
57
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 /**
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
59 * Terminate the program using the \ref panic_handler routine.
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 *
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 * This function will first set the global error with the provided format
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
62 * string and then call the handler.
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 *
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
64 * \pre fmt != NULL
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 * \param fmt the printf(3) format string
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
66 */
95
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
67 noreturn void
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
68 panicf(const char *fmt, ...) PLAT_PRINTF(1, 2);
88
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
69
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 /**
95
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
71 * Similar to \ref panicf but with a arguments pointer.
88
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 *
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
73 * \pre fmt != NULL
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 * \param fmt the printf(3) format string
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 * \param ap the arguments pointer
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
76 */
95
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
77 noreturn void
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
78 vpanicf(const char *fmt, va_list ap) PLAT_PRINTF(1, 0);
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
79
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
80 /**
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
81 * Similar to \ref panicf but use last error stored using \ref error.h
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
82 * routines.
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
83 */
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
84 noreturn void
e82eca4f8606 core: simplify error/panic routines
David Demelier <markand@malikania.fr>
parents: 88
diff changeset
85 panic(void);
88
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
86
44de3c528b63 core: implement basic panic mechanism, continue #2484 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 #endif /* !MOLKO_PANIC_H */