diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/src/sgml/html/source-conventions.html | 106 |
1 files changed, 106 insertions, 0 deletions
diff --git a/doc/src/sgml/html/source-conventions.html b/doc/src/sgml/html/source-conventions.html new file mode 100644 index 0000000..9475784 --- /dev/null +++ b/doc/src/sgml/html/source-conventions.html @@ -0,0 +1,106 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>56.4. Miscellaneous Coding Conventions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="error-style-guide.html" title="56.3. Error Message Style Guide" /><link rel="next" href="nls.html" title="Chapter 57. Native Language Support" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">56.4. Miscellaneous Coding Conventions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="error-style-guide.html" title="56.3. Error Message Style Guide">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><th width="60%" align="center">Chapter 56. PostgreSQL Coding Conventions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="nls.html" title="Chapter 57. Native Language Support">Next</a></td></tr></table><hr /></div><div class="sect1" id="SOURCE-CONVENTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">56.4. Miscellaneous Coding Conventions <a href="#SOURCE-CONVENTIONS" class="id_link">#</a></h2></div></div></div><div class="simplesect" id="SOURCE-CONVENTIONS-C-STANDARD"><div class="titlepage"><div><div><h3 class="title">C Standard <a href="#SOURCE-CONVENTIONS-C-STANDARD" class="id_link">#</a></h3></div></div></div><p> + Code in <span class="productname">PostgreSQL</span> should only rely on language + features available in the C99 standard. That means a conforming + C99 compiler has to be able to compile postgres, at least aside + from a few platform dependent pieces. + </p><p> + A few features included in the C99 standard are, at this time, not + permitted to be used in core <span class="productname">PostgreSQL</span> + code. This currently includes variable length arrays, intermingled + declarations and code, <code class="literal">//</code> comments, universal + character names. Reasons for that include portability and historical + practices. + </p><p> + Features from later revisions of the C standard or compiler specific + features can be used, if a fallback is provided. + </p><p> + For example <code class="literal">_Static_assert()</code> and + <code class="literal">__builtin_constant_p</code> are currently used, even though + they are from newer revisions of the C standard and a + <span class="productname">GCC</span> extension respectively. If not available + we respectively fall back to using a C99 compatible replacement that + performs the same checks, but emits rather cryptic messages and do not + use <code class="literal">__builtin_constant_p</code>. + </p></div><div class="simplesect" id="SOURCE-CONVENTIONS-MACROS-INLINE"><div class="titlepage"><div><div><h3 class="title">Function-Like Macros and Inline Functions <a href="#SOURCE-CONVENTIONS-MACROS-INLINE" class="id_link">#</a></h3></div></div></div><p> + Both macros with arguments and <code class="literal">static inline</code> + functions may be used. The latter are preferable if there are + multiple-evaluation hazards when written as a macro, as e.g., the + case with +</p><pre class="programlisting"> +#define Max(x, y) ((x) > (y) ? (x) : (y)) +</pre><p> + or when the macro would be very long. In other cases it's only + possible to use macros, or at least easier. For example because + expressions of various types need to be passed to the macro. + </p><p> + When the definition of an inline function references symbols + (i.e., variables, functions) that are only available as part of the + backend, the function may not be visible when included from frontend + code. +</p><pre class="programlisting"> +#ifndef FRONTEND +static inline MemoryContext +MemoryContextSwitchTo(MemoryContext context) +{ + MemoryContext old = CurrentMemoryContext; + + CurrentMemoryContext = context; + return old; +} +#endif /* FRONTEND */ +</pre><p> + In this example <code class="literal">CurrentMemoryContext</code>, which is only + available in the backend, is referenced and the function thus + hidden with a <code class="literal">#ifndef FRONTEND</code>. This rule + exists because some compilers emit references to symbols + contained in inline functions even if the function is not used. + </p></div><div class="simplesect" id="SOURCE-CONVENTIONS-SIGNAL-HANDLERS"><div class="titlepage"><div><div><h3 class="title">Writing Signal Handlers <a href="#SOURCE-CONVENTIONS-SIGNAL-HANDLERS" class="id_link">#</a></h3></div></div></div><p> + To be suitable to run inside a signal handler code has to be + written very carefully. The fundamental problem is that, unless + blocked, a signal handler can interrupt code at any time. If code + inside the signal handler uses the same state as code outside + chaos may ensue. As an example consider what happens if a signal + handler tries to acquire a lock that's already held in the + interrupted code. + </p><p> + Barring special arrangements code in signal handlers may only + call async-signal safe functions (as defined in POSIX) and access + variables of type <code class="literal">volatile sig_atomic_t</code>. A few + functions in <code class="command">postgres</code> are also deemed signal safe, importantly + <code class="function">SetLatch()</code>. + </p><p> + In most cases signal handlers should do nothing more than note + that a signal has arrived, and wake up code running outside of + the handler using a latch. An example of such a handler is the + following: +</p><pre class="programlisting"> +static void +handle_sighup(SIGNAL_ARGS) +{ + int save_errno = errno; + + got_SIGHUP = true; + SetLatch(MyLatch); + + errno = save_errno; +} +</pre><p> + <code class="varname">errno</code> is saved and restored because + <code class="function">SetLatch()</code> might change it. If that were not done + interrupted code that's currently inspecting <code class="varname">errno</code> might see the wrong + value. + </p></div><div class="simplesect" id="SOURCE-CONVENTIONS-FUNCTION-POINTERS"><div class="titlepage"><div><div><h3 class="title">Calling Function Pointers <a href="#SOURCE-CONVENTIONS-FUNCTION-POINTERS" class="id_link">#</a></h3></div></div></div><p> + For clarity, it is preferred to explicitly dereference a function pointer + when calling the pointed-to function if the pointer is a simple variable, + for example: +</p><pre class="programlisting"> +(*emit_log_hook) (edata); +</pre><p> + (even though <code class="literal">emit_log_hook(edata)</code> would also work). + When the function pointer is part of a structure, then the extra + punctuation can and usually should be omitted, for example: +</p><pre class="programlisting"> +paramInfo->paramFetch(paramInfo, paramId); +</pre><p> + </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="error-style-guide.html" title="56.3. Error Message Style Guide">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="nls.html" title="Chapter 57. Native Language Support">Next</a></td></tr><tr><td width="40%" align="left" valign="top">56.3. Error Message Style Guide </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 57. Native Language Support</td></tr></table></div></body></html>
\ No newline at end of file |