hphp/runtime/base/static-string-table.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-present Facebook, Inc. (http://www.facebook.com)  |
   6    +----------------------------------------------------------------------+
   7    | This source file is subject to version 3.01 of the PHP license,      |
   8    | that is bundled with this package in the file LICENSE, and is        |
   9    | available through the world-wide-web at the following url:           |
  10    | http://www.php.net/license/3_01.txt                                  |
  11    | If you did not receive a copy of the PHP license and are unable to   |
  12    | obtain it through the world-wide-web, please send a note to          |
  13    | license@php.net so we can mail you a copy immediately.               |
  14    +----------------------------------------------------------------------+
  15 */
  16 #ifndef incl_HPHP_STATIC_STRING_TABLE_H_
  17 #define incl_HPHP_STATIC_STRING_TABLE_H_
  18
  19 #include <string>
  20
  21 #include <folly/Range.h>
  22
  23 #include "hphp/runtime/base/rds.h"
  24
  25 namespace HPHP {
  26
  27 //////////////////////////////////////////////////////////////////////
  28
  29 struct Array;
  30 struct StringData;
  31 struct String;
  32 struct TypedValue;
  33 using Cell = TypedValue;
  34
  35 //////////////////////////////////////////////////////////////////////
  36
  37 /*
  38  * Process-lifetime strings are allocated using a table managed
  39  * through this api.
  40  *
  41  * We refer to these strings as "static strings"---they may be passed
  42  * around like request local strings, but have a bit set in their
  43  * reference count which indicates they should not actually be
  44  * incref'd or decref'd, and therefore are never freed. Furthermore,
  45  * any string marked static must be in the table and therefore can
  46  * be compared by pointer.
  47  *
  48  * Note that when a static or uncounted string is in a TypedValue,
  49  * it may or may not have KindOfPersistentString. (But no non-persistent
  50  * strings will ever have KindOfPersistentString.) so-called "uncounted"
  51  * strings are persistent (not ref counted) but not static.
  52  *
  53  * Because all constants defined in hhvm programs create a
  54  * process-lifetime string for the constant name, this module also
  55  * manages a mapping from constant names to rds::Handles.
  56  */
  57
  58 //////////////////////////////////////////////////////////////////////
  59
  60 extern StringData** precomputed_chars;
  61
  62 /*
  63  * Attempt to lookup a string (specified in various ways) in the
  64  * static string table.  If it's not there, create a new static string
  65  * and return it.
  66  */
  67 StringData* makeStaticString(const StringData* str);
  68 StringData* makeStaticString(folly::StringPiece);
  69 StringData* makeStaticString(const std::string& str);
  70 StringData* makeStaticString(const String& str);
  71 StringData* makeStaticString(const char* str, size_t len);
  72 StringData* makeStaticString(const char* str);
  73
  74 /*
  75  * As their counterparts above, but check that the static string
  76  * table has been initialized. These should be used for anything
  77  * that might run before main().
  78  */
  79 StringData* makeStaticStringSafe(const char* str, size_t len);
  80 StringData* makeStaticStringSafe(const char* str);
  81
  82 /*
  83  * Lookup static strings for single character strings.  (We pre-create
  84  * static strings for all 256 characters at process startup.)
  85  */
  86 StringData* makeStaticString(char c);
  87
  88 /*
  89  * Attempt to look up a static string for `str' if it exists, without
  90  * inserting it if not. Requires the input string to be known non-static.
  91  *
  92  * Returns: a string that isStatic(), or nullptr if there was none.
  93  */
  94 StringData* lookupStaticString(const StringData* str);
  95
  96 /*
  97  * Return the number of static strings in the process.
  98  */
  99 size_t makeStaticStringCount();
 100
 101 /*
 102  * Return total size of static strings in bytes
 103  */
 104 size_t makeStaticStringSize();
 105
 106 /*
 107  * Functions mapping constants to RDS handles to their values in a
 108  * given request.
 109  */
 110 rds::Handle lookupCnsHandle(const StringData* cnsName);
 111 rds::Handle makeCnsHandle(const StringData* cnsName);
 112
 113 /*
 114  * Bind a persistent constant if its not yet been bound.
 115  *
 116  * Returns true iff the constant has a persistent handle.
 117  */
 118 bool bindPersistentCns(const StringData* cnsName, const Cell& value);
 119
 120 /*
 121  * Return an array of all the static strings in the current
 122  * execution context.
 123  */
 124 std::vector<StringData*> lookupDefinedStaticStrings();
 125
 126 /*
 127  * Return an array of all the defined constants in the current
 128  * execution context.
 129  */
 130 Array lookupDefinedConstants(bool categorize = false);
 131
 132 /*
 133  * Return the number of static strings that correspond to defined
 134  * constants.
 135  */
 136 size_t countStaticStringConstants();
 137
 138 /*
 139  * The static string table is generally initially created before main
 140  * by global constructors (StaticString objects).  After we've parsed
 141  * options, we may find out a different size was requested for the
 142  * table.
 143  *
 144  * This function is called after runtime option parsing to
 145  * conditionally resize the table if its size was wrong.  We must
 146  * still be in a single-threaded environment.
 147  */
 148 void refineStaticStringTableSize();
 149
 150 //////////////////////////////////////////////////////////////////////
 151
 152 }
 153
 154 #endif