codekingpro/portable-devtools
115k
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!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.3 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>3 Code in <span class="productname">PostgreSQL</span> should only rely on language4 features available in the C99 standard. That means a conforming5 C99 compiler has to be able to compile postgres, at least aside6 from a few platform dependent pieces.7 </p><p>8 A few features included in the C99 standard are, at this time, not9 permitted to be used in core <span class="productname">PostgreSQL</span>10 code. This currently includes variable length arrays, intermingled11 declarations and code, <code class="literal">//</code> comments, universal12 character names. Reasons for that include portability and historical13 practices.14 </p><p>15 Features from later revisions of the C standard or compiler specific16 features can be used, if a fallback is provided.17 </p><p>18 For example <code class="literal">_Static_assert()</code> and19 <code class="literal">__builtin_constant_p</code> are currently used, even though20 they are from newer revisions of the C standard and a21 <span class="productname">GCC</span> extension respectively. If not available22 we respectively fall back to using a C99 compatible replacement that23 performs the same checks, but emits rather cryptic messages and do not24 use <code class="literal">__builtin_constant_p</code>.25 </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>26 Both macros with arguments and <code class="literal">static inline</code>27 functions may be used. The latter are preferable if there are28 multiple-evaluation hazards when written as a macro, as e.g., the29 case with30</p><pre class="programlisting">31#define Max(x, y) ((x) > (y) ? (x) : (y))32</pre><p>33 or when the macro would be very long. In other cases it's only34 possible to use macros, or at least easier. For example because35 expressions of various types need to be passed to the macro.36 </p><p>37 When the definition of an inline function references symbols38 (i.e., variables, functions) that are only available as part of the39 backend, the function may not be visible when included from frontend40 code.41</p><pre class="programlisting">42#ifndef FRONTEND43static inline MemoryContext44MemoryContextSwitchTo(MemoryContext context)45{46 MemoryContext old = CurrentMemoryContext;47 48 CurrentMemoryContext = context;49 return old;50}51#endif /* FRONTEND */52</pre><p>53 In this example <code class="literal">CurrentMemoryContext</code>, which is only54 available in the backend, is referenced and the function thus55 hidden with a <code class="literal">#ifndef FRONTEND</code>. This rule56 exists because some compilers emit references to symbols57 contained in inline functions even if the function is not used.58 </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>59 To be suitable to run inside a signal handler code has to be60 written very carefully. The fundamental problem is that, unless61 blocked, a signal handler can interrupt code at any time. If code62 inside the signal handler uses the same state as code outside63 chaos may ensue. As an example consider what happens if a signal64 handler tries to acquire a lock that's already held in the65 interrupted code.66 </p><p>67 Barring special arrangements code in signal handlers may only68 call async-signal safe functions (as defined in POSIX) and access69 variables of type <code class="literal">volatile sig_atomic_t</code>. A few70 functions in <code class="command">postgres</code> are also deemed signal safe, importantly71 <code class="function">SetLatch()</code>.72 </p><p>73 In most cases signal handlers should do nothing more than note74 that a signal has arrived, and wake up code running outside of75 the handler using a latch. An example of such a handler is the76 following:77</p><pre class="programlisting">78static void79handle_sighup(SIGNAL_ARGS)80{81 int save_errno = errno;82 83 got_SIGHUP = true;84 SetLatch(MyLatch);85 86 errno = save_errno;87}88</pre><p>89 <code class="varname">errno</code> is saved and restored because90 <code class="function">SetLatch()</code> might change it. If that were not done91 interrupted code that's currently inspecting <code class="varname">errno</code> might see the wrong92 value.93 </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>94 For clarity, it is preferred to explicitly dereference a function pointer95 when calling the pointed-to function if the pointer is a simple variable,96 for example:97</p><pre class="programlisting">98(*emit_log_hook) (edata);99</pre><p>100 (even though <code class="literal">emit_log_hook(edata)</code> would also work).101 When the function pointer is part of a structure, then the extra102 punctuation can and usually should be omitted, for example:103</p><pre class="programlisting">104paramInfo->paramFetch(paramInfo, paramId);105</pre><p>106 </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.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 57. Native Language Support</td></tr></table></div></body></html>