hphp/runtime/base/php-globals.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-2013 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_PHP_GLOBALS_H_
  17 #define incl_HPHP_PHP_GLOBALS_H_
  18
  19 namespace HPHP {
  20
  21 //////////////////////////////////////////////////////////////////////
  22
  23 struct StaticString;
  24 struct Variant;
  25 struct TypedValue;
  26 struct Array;
  27
  28 //////////////////////////////////////////////////////////////////////
  29
  30 /*
  31  * Set a $GLOBALS[foo] to the supplied value, using normal php set
  32  * semantics.  (I.e. if the global is a KindOfRef, this will set the
  33  * value in its RefData.)
  34  */
  35 void php_global_set(const StaticString&, Variant);
  36
  37 /*
  38  * Exchange a value in $GLOBALS.
  39  *
  40  * This sets $GLOBALS[key] to newV, and returns its previous value.
  41  * This is sometimes particularly useful if you want to temporarily
  42  * take an Array out of $GLOBALS so it can be modified with its
  43  * reference count as one, and then stored back in.
  44  *
  45  * For example:
  46  *
  47  *     auto arr = php_global_exchange(s_MyKey, uninit_null());
  48  *     arr.set(123, "foo");
  49  *     php_globals_set(s_MyKey, std::move(arr));
  50  */
  51 Variant php_global_exchange(const StaticString& key, Variant newV);
  52
  53 /*
  54  * Strong bind a value to $GLOBALS, making the value into a Ref if it
  55  * isn't one already.
  56  */
  57 void php_global_bind(const StaticString&, Variant&);
  58
  59 /*
  60  * Read a variable from $GLOBALS, returning a temporary for read-only
  61  * access.
  62  *
  63  * Returns a KindOfNull if the global didn't exist, without changing
  64  * $GLOBALS.
  65  */
  66 Variant php_global(const StaticString&);
  67
  68 /*
  69  * Return access to $GLOBALS as an Array.
  70  *
  71  * Note that the $GLOBALS Array behaves a bit differently than normal
  72  * PHP arrays: it doesn't do COW, and you need to be much more careful
  73  * with things like lvalAt or rvalPos, since anything that can
  74  * invoke arbitrary php-code (e.g. a set invoking an object
  75  * destructor) could turn around and clobber your pointer, where
  76  * normally you were protected from that by the COW/value semantics of
  77  * php arrays.  (If this doesn't make sense, please don't try to use
  78  * any of those APIs with this array.)
  79  *
  80  * Sometimes, however, it's still necessary to deal with globals using
  81  * a generic Array in extension code.  This function gives you that,
  82  * but keep in mind that if you are just doing lookups, the above
  83  * functions will be more efficient.
  84  */
  85 Array php_globals_as_array();
  86
  87 //////////////////////////////////////////////////////////////////////
  88
  89 }
  90
  91 #include "hphp/runtime/base/php-globals-inl.h"
  92
  93 #endif