6

How does the PHP Internals TSRMLS_FETCH macro do its job?

Per the PHP Manual

While developing extensions, build errors that contain "tsrm_ls is undefined" or errors to that effect stem from the fact that TSRMLS is undefined in the current scope, to fix this, declare the function to accept TSRMLS with the appropriate macro, if the prototype of the function in question cannot be changed, you must call TSRMLS_FETCH within the function body.

I understand that declaring the function to accept TSRMLS with the appropriate macros means using TSRMLS_C, TSRMLS_D, TSRMLS_CC, and TSRMLS_DC to either define of call a function with extra parameters/arguments.

However, if the prototype of the function in question cannot be changed, you must call TSRMLS_FETCH within the function body confuses me a bit. If I look at the php-src both here and here the TSRMLS_FETCH seems to be an empty macro.

So that leaves me with the question -- how does TSRMLS_FETCH even work? Is something else populating this macro at compile time?

Alana Storm
  • 164,128
  • 91
  • 395
  • 599

4 Answers4

4

Firstly, I would not pay too much attention to what the manual says on PHP's internals. It is very outdated, and there's a good chance it is going to be removed from the manual in the near future. There are two websites currently dedicated to PHP's internals: PHPInternalsBook.com and PHPInternals.net (I author content for the latter). There's also a couple of good blogs to follow, including Nikita's and Julien's.

The TSRM in PHP's 5.x series was quite invasive. When wanting to access any Zend globals from within a function, the choice was between either fetching the TLS memory pointer from a function call (such as pthread_getspecific, which was relatively expensive) or propagating the TLS memory pointer through function parameters (a messy and error-prone affair, but the faster way). The TSRMLS_FETCH macro you mentioned was used for the former approach.

In PHP 7.x, propagating the TLS memory pointer (via the TSRMLS_[D|C]C? macros) has been removed completely (though their macros are still defined for backwards compatibility - they just won't do anything). The preferred way to access the TSRM's TLS now is via its static cache. This is basically just a thread local global variable used to hold the current TLS memory pointer.

Here are the relevant macros:

#define TSRMLS_CACHE _tsrm_ls_cache // the TLS global variable
#define TSRMLS_CACHE_DEFINE() TSRM_TLS void *TSRMLS_CACHE = NULL; // define it
#define TSRMLS_CACHE_UPDATE() TSRMLS_CACHE = tsrm_get_ls_cache() // update it - i.e. calls pthread_getspecific()
#define TSRMLS_CACHE_RESET()  TSRMLS_CACHE = NULL // reset it

Using the above macros does require special care to update the static cache appropriately (usually during the GINIT, and sometimes RINIT, phases of an extension). However, it is a cleaner way to provide access to the TLS memory pointer without the mess of propagating it via function parameters or the performance hit of always fetching it (via pthread_getspecific and similar).

Extra reading:

mvorisek
  • 3,290
  • 2
  • 18
  • 53
tpunt
  • 2,552
  • 1
  • 12
  • 18
  • Thank you @tpunt! I stumbled across the PHPInternals.net earlier this year and it was a breath of fresh air. I also wan't aware of Nikita or Julien's site, so they're going to the top of my reading list. – Alana Storm Apr 01 '18 at 15:05
3

Take a look at older versions of that file:

#define TSRMLS_FETCH()            void ***tsrm_ls = (void ***) ts_resource_ex(0, NULL)
#define TSRMG(id, type, element)  (((type) (*((void ***) tsrm_ls))[TSRM_UNSHUFFLE_RSRC_ID(id)])->element)
#define TSRMLS_D  void ***tsrm_ls
#define TSRMLS_DC , TSRMLS_D
#define TSRMLS_C  tsrm_ls
#define TSRMLS_CC , TSRMLS_C

It seems at some point PHP removed support for those macros but kept them empty in order to avoid having to split external code in two versions, one for the new PHP and one for the old PHP.

Acorn
  • 24,970
  • 5
  • 40
  • 69
  • 2
    Ah ha! It looks like the last version of PHP to use/need these macros was PHP 5.6 -- https://github.com/php/php-src/blob/PHP-5.6/TSRM/TSRM.h. Thank you, this was the answer I was looking for! – Alana Storm Mar 28 '18 at 17:04
1

This piece of code

#if ZEND_DEBUG
...
#else
#define TSRMLS_FETCH()
...
#endif

Is doing the following:

If you are not in debug mode, change each call to the macro TSRMLS_FETCH() with nothing.

In this example:

#if 0
#define TSRMLS_FETCH() printf("Bla");
#else
#define TSRMLS_FETCH()
#endif

int main(void) 
{
    TSRMLS_FETCH()
    return 0;
}

cpp demo.c (preprocessor output) returns:

int main(void) 
{
    return 0;
}
David Ranieri
  • 39,972
  • 7
  • 52
  • 94
  • 1
    Thank you for responding, and +1 for the useful general information about macro `#ifdef` handling. I appreciate it. However -- in both conditions the `TSRMLS_FETCH` macro resolves to empty text, so this doesn't directly answer my question. – Alana Storm Mar 28 '18 at 16:58
  • I see, maybe this macro is defined in another `include` or in an old version and this one prevents to use the code in ZEND_DEBUG mode. – David Ranieri Mar 28 '18 at 17:06
  • 1
    It was the second one -- older versions of PHP <7.0 needed these macros, but >=7.0 do not. It looks like the internals folks left them defined so that they, and people with multi-version PHP extensions, wouldn't need to do a big refactoring. – Alana Storm Mar 28 '18 at 17:08
1

In PHP 8 (in Alhpa fase at the moment I am writing this) a lot of these macro's have been removed. See https://github.com/php/php-src/blob/master/UPGRADING.INTERNALS

c. The following things have been removed from TSRM:
    - TSRMLS_DC
    - TSRMLS_D
    - TSRMLS_CC
    - TSRMLS_C
    - TSRMLS_FETCH
    - TSRMLS_FETCH_FROM_CTX
    - TSRMLS_SET_CTX
    - tsrm_new_interpreter_context
    - tsrm_set_interpreter_context
    - tsrm_free_interpreter_context
    - support for GNUPTH, SGI ST, and BETHREADS
Jan Ehrhardt
  • 395
  • 1
  • 8
  • 20