root/src/pdumper.h

INCLUDED FROM

DEFINITIONS

1. pdumper_remember_scalar
2. pdumper_remember_lv_ptr_raw
3. pdumper_do_now_and_after_load
4. pdumper_do_now_and_after_late_load
5. pdumper_object_p
6. pdumper_cold_object_p
7. pdumper_find_object_type
8. pdumper_valid_object_type_p
9. pdumper_object_p_precise
10. pdumper_marked_p
11. pdumper_set_marked
12. pdumper_clear_marks

     1 /* Header file for the portable dumper.
     2 
     3 Copyright (C) 2016, 2018-2023 Free Software Foundation, Inc.
     4 
     5 This file is part of GNU Emacs.
     6 
     7 GNU Emacs is free software: you can redistribute it and/or modify
     8 it under the terms of the GNU General Public License as published by
     9 the Free Software Foundation, either version 3 of the License, or (at
    10 your option) any later version.
    11 
    12 GNU Emacs is distributed in the hope that it will be useful,
    13 but WITHOUT ANY WARRANTY; without even the implied warranty of
    14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    15 GNU General Public License for more details.
    16 
    17 You should have received a copy of the GNU General Public License
    18 along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
    19 
    20 #ifndef EMACS_PDUMPER_H
    21 #define EMACS_PDUMPER_H
    22 
    23 #include <stdio.h>
    24 #include "fingerprint.h"
    25 #include "lisp.h"
    26 
    27 INLINE_HEADER_BEGIN
    28 
    29 enum { PDUMPER_NO_OBJECT = -1 };
    30 
    31 /* Indicate in source code that we're deliberately relying on pdumper
    32    not preserving the given value.  Compiles to nothing --- for humans
    33    only.  */
    34 #define PDUMPER_IGNORE(thing) ((void) &(thing))
    35 
    36 /* The portable dumper automatically preserves the Lisp heap and any C
    37    variables to which the Lisp heap points.  It doesn't know anything
    38    about other C variables.  The functions below allow code from other
    39    parts of Emacs to tell the portable dumper about other bits of
    40    information to preserve in dump files.
    41 
    42    These memory-records are themselves preserved in the dump, so call
    43    the functions below only on the !initialized init path, just
    44    like staticpro.
    45 
    46    There are no special functions to preserve a global Lisp_Object.
    47    You should just staticpro these.  */
    48 
    49 /* Remember the value of THING in dump files.  THING must not
    50    contain any pointers or Lisp_Object variables: these values are not
    51    valid across dump and load.  */
    52 #define PDUMPER_REMEMBER_SCALAR(thing)                  \
    53   pdumper_remember_scalar (&(thing), sizeof (thing))
    54 
    55 extern void dump_fingerprint (FILE *output, const char *label,
    56                               unsigned char const fingerp[sizeof fingerprint]);
    57 
    58 extern void pdumper_remember_scalar_impl (void *data, ptrdiff_t nbytes);
    59 
    60 INLINE void
    61 pdumper_remember_scalar (void *data, ptrdiff_t nbytes)
    62 {
    63 #ifdef HAVE_PDUMPER
    64   pdumper_remember_scalar_impl (data, nbytes);
    65 #else
    66   (void) data;
    67   (void) nbytes;
    68 #endif
    69 }
    70 
    71 extern void pdumper_remember_lv_ptr_raw_impl (void *ptr, enum Lisp_Type type);
    72 
    73 /* Remember the pointer at *PTR.  *PTR must be null or point to a Lisp
    74    object.  TYPE is the rough type of Lisp object to which *PTR
    75    points.  */
    76 INLINE void
    77 pdumper_remember_lv_ptr_raw (void *ptr, enum Lisp_Type type)
    78 {
    79 #ifdef HAVE_PDUMPER
    80   pdumper_remember_lv_ptr_raw_impl (ptr, type);
    81 #else
    82   (void) ptr;
    83   (void) type;
    84 #endif
    85 }
    86 
    87 typedef void (*pdumper_hook)(void);
    88 extern void pdumper_do_now_and_after_load_impl (pdumper_hook hook);
    89 extern void pdumper_do_now_and_after_late_load_impl (pdumper_hook hook);
    90 
    91 INLINE void
    92 pdumper_do_now_and_after_load (pdumper_hook hook)
    93 {
    94 #ifdef HAVE_PDUMPER
    95   pdumper_do_now_and_after_load_impl (hook);
    96 #else
    97   hook ();
    98 #endif
    99 }
   100 
   101 /* Same as 'pdumper_do_now_and_after_load' but for hooks running code
   102    that can call into Lisp.  */
   103 INLINE void
   104 pdumper_do_now_and_after_late_load (pdumper_hook hook)
   105 {
   106 #ifdef HAVE_PDUMPER
   107   pdumper_do_now_and_after_late_load_impl (hook);
   108 #else
   109   hook ();
   110 #endif
   111 }
   112 
   113 /* Macros useful in pdumper callback functions.  Assign a value if
   114    we're loading a dump and the value needs to be reset to its
   115    original value, and if we're initializing for the first time,
   116    assert that the value has the expected original value.  */
   117 
   118 #define PDUMPER_RESET(variable, value)         \
   119   do {                                         \
   120     if (dumped_with_pdumper_p ())              \
   121       (variable) = (value);                    \
   122     else                                       \
   123       eassert ((variable) == (value));         \
   124   } while (0)
   125 
   126 #define PDUMPER_RESET_LV(variable, value)         \
   127   do {                                            \
   128     if (dumped_with_pdumper_p ())                 \
   129       (variable) = (value);                       \
   130     else                                          \
   131       eassert (EQ ((variable), (value)));         \
   132   } while (0)
   133 
   134 /* Actually load a dump.  */
   135 
   136 enum pdumper_load_result
   137   {
   138     PDUMPER_LOAD_SUCCESS,
   139     PDUMPER_NOT_LOADED /* Not returned: useful for callers */,
   140     PDUMPER_LOAD_FILE_NOT_FOUND,
   141     PDUMPER_LOAD_BAD_FILE_TYPE,
   142     PDUMPER_LOAD_FAILED_DUMP,
   143     PDUMPER_LOAD_OOM,
   144     PDUMPER_LOAD_VERSION_MISMATCH,
   145     PDUMPER_LOAD_ERROR /* Must be last, as errno may be added.  */
   146   };
   147 
   148 int pdumper_load (const char *dump_filename, char *argv0);
   149 
   150 struct pdumper_loaded_dump
   151 {
   152   uintptr_t start;
   153   uintptr_t end;
   154 };
   155 
   156 extern struct pdumper_loaded_dump dump_public;
   157 
   158 /* Return whether the OBJ points somewhere into the loaded dump image.
   159    Works even when we have no dump loaded --- in this case, it just
   160    returns false.  */
   161 INLINE _GL_ATTRIBUTE_CONST bool
   162 pdumper_object_p (const void *obj)
   163 {
   164 #ifdef HAVE_PDUMPER
   165   uintptr_t obj_addr = (uintptr_t) obj;
   166   return dump_public.start <= obj_addr && obj_addr < dump_public.end;
   167 #else
   168   (void) obj;
   169   return false;
   170 #endif
   171 }
   172 
   173 extern bool pdumper_cold_object_p_impl (const void *obj);
   174 
   175 /* Return whether the OBJ is in the cold section of the dump.
   176    Only bool-vectors and floats should end up there.
   177    pdumper_object_p() and pdumper_object_p_precise() must have
   178    returned true for OBJ before calling this function.  */
   179 INLINE _GL_ATTRIBUTE_CONST bool
   180 pdumper_cold_object_p (const void *obj)
   181 {
   182 #ifdef HAVE_PDUMPER
   183   return pdumper_cold_object_p_impl (obj);
   184 #else
   185   (void) obj;
   186   return false;
   187 #endif
   188 }
   189 
   190 
   191 extern int pdumper_find_object_type_impl (const void *obj);
   192 
   193 /* Return the type of the dumped object that starts at OBJ.  It is a
   194    programming error to call this routine for an OBJ for which
   195    pdumper_object_p would return false.  */
   196 INLINE _GL_ATTRIBUTE_CONST int
   197 pdumper_find_object_type (const void *obj)
   198 {
   199 #ifdef HAVE_PDUMPER
   200   return pdumper_find_object_type_impl (obj);
   201 #else
   202   (void) obj;
   203   emacs_abort ();
   204 #endif
   205 }
   206 
   207 /* Return true if TYPE is that of a Lisp object.
   208    PDUMPER_NO_OBJECT is invalid.  */
   209 INLINE bool
   210 pdumper_valid_object_type_p (int type)
   211 {
   212   return 0 <= type;
   213 }
   214 
   215 /* Return whether OBJ points exactly to the start of some object in
   216    the loaded dump image.  It is a programming error to call this
   217    routine for an OBJ for which pdumper_object_p would return
   218    false.  */
   219 INLINE _GL_ATTRIBUTE_CONST bool
   220 pdumper_object_p_precise (const void *obj)
   221 {
   222 #ifdef HAVE_PDUMPER
   223   return pdumper_valid_object_type_p (pdumper_find_object_type (obj));
   224 #else
   225   (void) obj;
   226   emacs_abort ();
   227 #endif
   228 }
   229 
   230 extern bool pdumper_marked_p_impl (const void *obj);
   231 
   232 /* Return whether OBJ is marked according to the portable dumper.
   233    It is an error to call this routine for an OBJ for which
   234    pdumper_object_p_precise would return false.  */
   235 INLINE bool
   236 pdumper_marked_p (const void *obj)
   237 {
   238 #ifdef HAVE_PDUMPER
   239   return pdumper_marked_p_impl (obj);
   240 #else
   241   (void) obj;
   242   emacs_abort ();
   243 #endif
   244 }
   245 
   246 extern void pdumper_set_marked_impl (const void *obj);
   247 
   248 /* Set the pdumper mark bit for OBJ.  It is a programming error to
   249    call this function with an OBJ for which pdumper_object_p_precise
   250    would return false.  */
   251 INLINE void
   252 pdumper_set_marked (const void *obj)
   253 {
   254 #ifdef HAVE_PDUMPER
   255   pdumper_set_marked_impl (obj);
   256 #else
   257   (void) obj;
   258   emacs_abort ();
   259 #endif
   260 }
   261 
   262 extern void pdumper_clear_marks_impl (void);
   263 
   264 /* Clear all the mark bits for pdumper objects.  */
   265 INLINE void
   266 pdumper_clear_marks (void)
   267 {
   268 #ifdef HAVE_PDUMPER
   269   pdumper_clear_marks_impl ();
   270 #endif
   271 }
   272 
   273 /* Record the Emacs startup directory, relative to which the pdump
   274    file was loaded.  */
   275 extern void pdumper_record_wd (const char *);
   276 
   277 void init_pdumper_once (void);
   278 void syms_of_pdumper (void);
   279 
   280 INLINE_HEADER_END
   281 #endif