begriffs open source - ai-pg/blob - full-docs/html/source-conventions.html

   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>55.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="55.3. Error Message Style Guide" /><link rel="next" href="nls.html" title="Chapter 56. 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">55.4. Miscellaneous Coding Conventions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="error-style-guide.html" title="55.3. Error Message Style Guide">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="source.html" title="Chapter 55. PostgreSQL Coding Conventions">Up</a></td><th width="60%" align="center">Chapter 55. PostgreSQL Coding Conventions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="nls.html" title="Chapter 56. 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">55.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 language
   4      features available in the C99 standard. That means a conforming
   5      C99 compiler has to be able to compile postgres, at least aside
   6      from a few platform dependent pieces.
   7     </p><p>
   8      A few features included in the C99 standard are, at this time, not
   9      permitted to be used in core <span class="productname">PostgreSQL</span>
  10      code. This currently includes variable length arrays, intermingled
  11      declarations and code, <code class="literal">//</code> comments, universal
  12      character names. Reasons for that include portability and historical
  13      practices.
  14     </p><p>
  15      Features from later revisions of the C standard or compiler specific
  16      features can be used, if a fallback is provided.
  17     </p><p>
  18      For example <code class="literal">_Static_assert()</code> and
  19      <code class="literal">__builtin_constant_p</code> are currently used, even though
  20      they are from newer revisions of the C standard and a
  21      <span class="productname">GCC</span> extension respectively. If not available
  22      we respectively fall back to using a C99 compatible replacement that
  23      performs the same checks, but emits rather cryptic messages and do not
  24      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 are
  28      multiple-evaluation hazards when written as a macro, as e.g., the
  29      case with
  30 </p><pre class="programlisting">
  31 #define Max(x, y)       ((x) &gt; (y) ? (x) : (y))
  32 </pre><p>
  33      or when the macro would be very long. In other cases it's only
  34      possible to use macros, or at least easier.  For example because
  35      expressions of various types need to be passed to the macro.
  36     </p><p>
  37      When the definition of an inline function references symbols
  38      (i.e., variables, functions) that are only available as part of the
  39      backend, the function may not be visible when included from frontend
  40      code.
  41 </p><pre class="programlisting">
  42 #ifndef FRONTEND
  43 static inline MemoryContext
  44 MemoryContextSwitchTo(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 only
  54      available in the backend, is referenced and the function thus
  55      hidden with a <code class="literal">#ifndef FRONTEND</code>. This rule
  56      exists because some compilers emit references to symbols
  57      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 be
  60      written very carefully. The fundamental problem is that, unless
  61      blocked, a signal handler can interrupt code at any time. If code
  62      inside the signal handler uses the same state as code outside
  63      chaos may ensue. As an example consider what happens if a signal
  64      handler tries to acquire a lock that's already held in the
  65      interrupted code.
  66     </p><p>
  67      Barring special arrangements code in signal handlers may only
  68      call async-signal safe functions (as defined in POSIX) and access
  69      variables of type <code class="literal">volatile sig_atomic_t</code>. A few
  70      functions in <code class="command">postgres</code> are also deemed signal safe, importantly
  71      <code class="function">SetLatch()</code>.
  72     </p><p>
  73      In most cases signal handlers should do nothing more than note
  74      that a signal has arrived, and wake up code running outside of
  75      the handler using a latch. An example of such a handler is the
  76      following:
  77 </p><pre class="programlisting">
  78 static void
  79 handle_sighup(SIGNAL_ARGS)
  80 {
  81     got_SIGHUP = true;
  82     SetLatch(MyLatch);
  83 }
  84 </pre><p>
  85     </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>
  86      For clarity, it is preferred to explicitly dereference a function pointer
  87      when calling the pointed-to function if the pointer is a simple variable,
  88      for example:
  89 </p><pre class="programlisting">
  90 (*emit_log_hook) (edata);
  91 </pre><p>
  92      (even though <code class="literal">emit_log_hook(edata)</code> would also work).
  93      When the function pointer is part of a structure, then the extra
  94      punctuation can and usually should be omitted, for example:
  95 </p><pre class="programlisting">
  96 paramInfo-&gt;paramFetch(paramInfo, paramId);
  97 </pre><p>
  98     </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="55.3. Error Message Style Guide">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="source.html" title="Chapter 55. PostgreSQL Coding Conventions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="nls.html" title="Chapter 56. Native Language Support">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.3. Error Message Style Guide </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 56. Native Language Support</td></tr></table></div></body></html>