Deprecate allocateUTF8 in favor of stringToNewUTF8 (#19089)

Followup to #19064

Author: sbc100

ChangeLog.md

@@ -20,6 +20,8 @@ See docs/process.md for more on how version tagging works.
 
 3.1.35 (in development)
 -----------------------
+- `allocateUTF8` library function moved to `library_legacy.js`.  Prefer the
+  more accurately named `stringToNewUTF8`.
 - `SDL_image` port was updated to version 2.6.0.
 - `-z` arguments are now passed directly to wasm-ld without the need for the
   `-Wl,` prefix.  This matches the behaviour of both clang and gcc. (#18956)

site/source/docs/api_reference/emscripten.h.rst

@@ -111,7 +111,7 @@ Defines
       var jsString = 'Hello with some exotic Unicode characters: Tässä on yksi lumiukko: ☃, ole hyvä.';
       // 'jsString.length' would return the length of the string as UTF-16
       // units, but Emscripten C strings operate as UTF-8.
-      return allocateUTF8(jsString);
+      return stringToNewUTF8(jsString);
     });
 
     int main() {
@@ -191,7 +191,7 @@ Defines
       var lengthBytes = lengthBytesUTF8(jsString)+1;
       // 'jsString.length' would return the length of the string as UTF-16
       // units, but Emscripten C strings operate as UTF-8.
-      return allocateUTF8(jsString);
+      return stringToNewUTF8(jsString);
     });
     printf("UTF8 string says: %s\n", str);
     free(str); // Each call to _malloc() must be paired with free(), or heap memory will leak!

site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst

@@ -235,7 +235,7 @@ The parameters you pass to and receive from functions need to be primitive value
 
   - Integer and floating point numbers can be passed as-is.
   - Pointers can be passed as-is also, as they are simply integers in the generated code.
-  - JavaScript string ``someString`` can be converted to a ``char *`` using ``ptr = allocateUTF8(someString)``.
+  - JavaScript string ``someString`` can be converted to a ``char *`` using ``ptr = stringToNewUTF8(someString)``.
 
     .. note:: The conversion to a pointer allocates memory, which needs to be
       freed up via a call to ``free(ptr)`` afterwards (``_free`` in JavaScript side) -

src/library.js

@@ -52,8 +52,6 @@ mergeInto(LibraryManager.library, {
   // JavaScript <-> C string interop
   // ==========================================================================
 
-  $stringToNewUTF8: '$allocateUTF8',
-
 #if !MINIMAL_RUNTIME
   $exitJS__docs: '/** @param {boolean|number=} implicit */',
   $exitJS__deps: ['proc_exit'],
@@ -569,7 +567,7 @@ mergeInto(LibraryManager.library, {
 
   // TODO: Initialize these to defaults on startup from system settings.
   // Note: glibc has one fewer underscore for all of these. Also used in other related functions (timegm)
-  _tzset_js__deps: ['$allocateUTF8'],
+  _tzset_js__deps: ['$stringToNewUTF8'],
   _tzset_js__internal: true,
   _tzset_js: function(timezone, daylight, tzname) {
     // TODO: Use (malleable) environment variables instead of system settings.
@@ -599,8 +597,8 @@ mergeInto(LibraryManager.library, {
     };
     var winterName = extractZone(winter);
     var summerName = extractZone(summer);
-    var winterNamePtr = allocateUTF8(winterName);
-    var summerNamePtr = allocateUTF8(summerName);
+    var winterNamePtr = stringToNewUTF8(winterName);
+    var summerNamePtr = stringToNewUTF8(summerName);
     if (summerOffset < winterOffset) {
       // Northern hemisphere
       {{{ makeSetValue('tzname', '0', 'winterNamePtr', POINTER_TYPE) }}};
@@ -1827,11 +1825,11 @@ mergeInto(LibraryManager.library, {
     return getHostByName(UTF8ToString(name));
   },
 
-  $getHostByName__deps: ['malloc', '$allocateUTF8', '$DNS', '$inetPton4'],
+  $getHostByName__deps: ['malloc', '$stringToNewUTF8', '$DNS', '$inetPton4'],
   $getHostByName: function(name) {
     // generate hostent
     var ret = _malloc({{{ C_STRUCTS.hostent.__size__ }}}); // XXX possibly leaked, as are others here
-    var nameBuf = allocateUTF8(name);
+    var nameBuf = stringToNewUTF8(name);
     {{{ makeSetValue('ret', C_STRUCTS.hostent.h_name, 'nameBuf', POINTER_TYPE) }}};
     var aliasesBuf = _malloc(4);
     {{{ makeSetValue('aliasesBuf', '0', '0', POINTER_TYPE) }}};
@@ -2622,7 +2620,7 @@ mergeInto(LibraryManager.library, {
   // using builtin_malloc to avoid LSan reporting these as leaks.
   emscripten_get_compiler_setting__noleakcheck: true,
 #if RETAIN_COMPILER_SETTINGS
-  emscripten_get_compiler_setting__deps: ['$allocateUTF8'],
+  emscripten_get_compiler_setting__deps: ['$stringToNewUTF8'],
 #endif
   emscripten_get_compiler_setting: function(name) {
 #if RETAIN_COMPILER_SETTINGS
@@ -2635,7 +2633,7 @@ mergeInto(LibraryManager.library, {
     var cache = _emscripten_get_compiler_setting.cache;
     var fullret = cache[name];
     if (fullret) return fullret;
-    return cache[name] = allocateUTF8(ret);
+    return cache[name] = stringToNewUTF8(ret);
 #else
     throw 'You must build with -sRETAIN_COMPILER_SETTINGS for getCompilerSetting or emscripten_get_compiler_setting to work';
 #endif
@@ -2803,7 +2801,7 @@ mergeInto(LibraryManager.library, {
 
   // Look up the function name from our stack frame cache with our PC representation.
 #if USE_OFFSET_CONVERTER
-  emscripten_pc_get_function__deps: ['$UNWIND_CACHE', 'free', '$allocateUTF8'],
+  emscripten_pc_get_function__deps: ['$UNWIND_CACHE', 'free', '$stringToNewUTF8'],
   // Don't treat allocation of _emscripten_pc_get_function.ret as a leak
   emscripten_pc_get_function__noleakcheck: true,
 #endif
@@ -2829,7 +2827,7 @@ mergeInto(LibraryManager.library, {
       name = wasmOffsetConverter.getName(pc);
     }
     if (_emscripten_pc_get_function.ret) _free(_emscripten_pc_get_function.ret);
-    _emscripten_pc_get_function.ret = allocateUTF8(name);
+    _emscripten_pc_get_function.ret = stringToNewUTF8(name);
     return _emscripten_pc_get_function.ret;
 #endif
   },
@@ -2863,15 +2861,15 @@ mergeInto(LibraryManager.library, {
   },
 
   // Look up the file name from our stack frame cache with our PC representation.
-  emscripten_pc_get_file__deps: ['$convertPCtoSourceLocation', 'free', '$allocateUTF8'],
+  emscripten_pc_get_file__deps: ['$convertPCtoSourceLocation', 'free', '$stringToNewUTF8'],
   // Don't treat allocation of _emscripten_pc_get_file.ret as a leak
   emscripten_pc_get_file__noleakcheck: true,
   emscripten_pc_get_file: function (pc) {
     var result = convertPCtoSourceLocation(pc);
     if (!result) return 0;
 
     if (_emscripten_pc_get_file.ret) _free(_emscripten_pc_get_file.ret);
-    _emscripten_pc_get_file.ret = allocateUTF8(result.file);
+    _emscripten_pc_get_file.ret = stringToNewUTF8(result.file);
     return _emscripten_pc_get_file.ret;
   },
 
@@ -3714,7 +3712,7 @@ DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.push(
   '$UTF32ToString',
   '$stringToUTF32',
   '$lengthBytesUTF32',
-  '$allocateUTF8',
+  '$stringToNewUTF8',
   '$allocateUTF8OnStack',
   '$writeStringToMemory',
   '$writeArrayToMemory',

src/library_browser.js

@@ -803,14 +803,14 @@ var LibraryBrowser = {
   },
 
   emscripten_run_preload_plugins_data__proxy: 'sync',
-  emscripten_run_preload_plugins_data__deps: ['$allocateUTF8'],
+  emscripten_run_preload_plugins_data__deps: ['$stringToNewUTF8'],
   emscripten_run_preload_plugins_data: function(data, size, suffix, arg, onload, onerror) {
     {{{ runtimeKeepalivePush() }}}
 
     var _suffix = UTF8ToString(suffix);
     if (!Browser.asyncPrepareDataCounter) Browser.asyncPrepareDataCounter = 0;
     var name = 'prepare_data_' + (Browser.asyncPrepareDataCounter++) + '.' + _suffix;
-    var cname = allocateUTF8(name);
+    var cname = stringToNewUTF8(name);
     FS.createPreloadedFile(
       '/',
       name,

src/library_egl.js

@@ -520,7 +520,7 @@ var LibraryEGL = {
   },
 
   // EGLAPI const char * EGLAPIENTRY eglQueryString(EGLDisplay dpy, EGLint name);
-  eglQueryString__deps: ['$allocateUTF8'],
+  eglQueryString__deps: ['$stringToNewUTF8'],
   eglQueryString__proxy: 'sync',
   eglQueryString__sig: 'iii',
   eglQueryString: function(display, name) {
@@ -533,10 +533,10 @@ var LibraryEGL = {
     if (EGL.stringCache[name]) return EGL.stringCache[name];
     var ret;
     switch (name) {
-      case 0x3053 /* EGL_VENDOR */: ret = allocateUTF8("Emscripten"); break;
-      case 0x3054 /* EGL_VERSION */: ret = allocateUTF8("1.4 Emscripten EGL"); break;
-      case 0x3055 /* EGL_EXTENSIONS */:  ret = allocateUTF8(""); break; // Currently not supporting any EGL extensions.
-      case 0x308D /* EGL_CLIENT_APIS */: ret = allocateUTF8("OpenGL_ES"); break;
+      case 0x3053 /* EGL_VENDOR */: ret = stringToNewUTF8("Emscripten"); break;
+      case 0x3054 /* EGL_VERSION */: ret = stringToNewUTF8("1.4 Emscripten EGL"); break;
+      case 0x3055 /* EGL_EXTENSIONS */:  ret = stringToNewUTF8(""); break; // Currently not supporting any EGL extensions.
+      case 0x308D /* EGL_CLIENT_APIS */: ret = stringToNewUTF8("OpenGL_ES"); break;
       default:
         EGL.setErrorCode(0x300C /* EGL_BAD_PARAMETER */);
         return 0;

src/library_glew.js

@@ -20,7 +20,7 @@
  */
 
 var LibraryGLEW = {
-  $GLEW__deps: ['glGetString', '$allocateUTF8'],
+  $GLEW__deps: ['glGetString', '$stringToNewUTF8'],
   $GLEW: {
     isLinaroFork: 1,
     extensions: null,
@@ -73,7 +73,7 @@ var LibraryGLEW = {
           string = "Unknown error";
           error = 8; // prevent array from growing more than this
         }
-        GLEW.error[error] = allocateUTF8(string);
+        GLEW.error[error] = stringToNewUTF8(string);
       }
       return GLEW.error[error];
     },
@@ -93,7 +93,7 @@ var LibraryGLEW = {
         var string = GLEW.versionStringConstantFromCode(name);
         if (!string)
           return 0;
-        GLEW.version[name] = allocateUTF8(string);
+        GLEW.version[name] = stringToNewUTF8(string);
       }
       return GLEW.version[name];
     },

src/library_glfw.js

@@ -82,7 +82,7 @@ var LibraryGLFW = {
     },
 
   $GLFW__deps: ['emscripten_get_now', '$GL', '$Browser', '$GLFW_Window',
-    '$allocateUTF8',
+    '$stringToNewUTF8',
 #if FILESYSTEM
     '$FS',
 #endif
@@ -662,7 +662,7 @@ var LibraryGLFW = {
             if (!GLFW.joys[joy]) {
               out('glfw joystick connected:',joy);
               GLFW.joys[joy] = {
-                id: allocateUTF8(gamepad.id),
+                id: stringToNewUTF8(gamepad.id),
                 buttonsCount: gamepad.buttons.length,
                 axesCount: gamepad.axes.length,
                 buttons: _malloc(gamepad.buttons.length),
@@ -789,7 +789,7 @@ var LibraryGLFW = {
         };
         reader.readAsArrayBuffer(file);
 
-        var filename = allocateUTF8(path);
+        var filename = stringToNewUTF8(path);
         filenamesArray.push(filename);
         {{{ makeSetValue('filenames + i*4', '0', 'filename', POINTER_TYPE) }}};
       }
@@ -1251,7 +1251,7 @@ var LibraryGLFW = {
   glfwGetVersionString__sig: 'i',
   glfwGetVersionString: function() {
     if (!GLFW.versionString) {
-      GLFW.versionString = allocateUTF8("3.2.1 JS WebGL Emscripten");
+      GLFW.versionString = stringToNewUTF8("3.2.1 JS WebGL Emscripten");
     }
     return GLFW.versionString;
   },
@@ -1318,7 +1318,7 @@ var LibraryGLFW = {
   glfwGetMonitorName__sig: 'ii',
   glfwGetMonitorName: function(mon) {
     if (!GLFW.monitorString) {
-      GLFW.monitorString = allocateUTF8("HTML5 WebGL Canvas");
+      GLFW.monitorString = stringToNewUTF8("HTML5 WebGL Canvas");
     }
     return GLFW.monitorString;
   },

src/library_legacy.js

@@ -37,4 +37,6 @@ mergeInto(LibraryManager.library, {
     HEAPU8.set(slab, ret);
     return ret;
   },
+
+  $allocateUTF8: '$stringToNewUTF8',
 });

src/library_openal.js

@@ -2376,7 +2376,7 @@ var LibraryOpenAL = {
   },
 
   alcGetString__proxy: 'sync',
-  alcGetString__deps: ['$allocateUTF8'],
+  alcGetString__deps: ['$stringToNewUTF8'],
   alcGetString: function(deviceId, param) {
     if (AL.alcStringCache[param]) {
       return AL.alcStringCache[param];
@@ -2450,7 +2450,7 @@ var LibraryOpenAL = {
       return 0;
     }
 
-    ret = allocateUTF8(ret);
+    ret = stringToNewUTF8(ret);
     AL.alcStringCache[param] = ret;
     return ret;
   },
@@ -2631,7 +2631,7 @@ var LibraryOpenAL = {
 
   emscripten_alcGetStringiSOFT__proxy: 'sync',
   emscripten_alcGetStringiSOFT__sig: 'iiii',
-  emscripten_alcGetStringiSOFT__deps: ['alcGetString', '$allocateUTF8'],
+  emscripten_alcGetStringiSOFT__deps: ['alcGetString', '$stringToNewUTF8'],
   emscripten_alcGetStringiSOFT: function(deviceId, param, index) {
     if (!(deviceId in AL.deviceRefCounts)) {
 #if OPENAL_DEBUG
@@ -2669,7 +2669,7 @@ var LibraryOpenAL = {
       return _alcGetString(deviceId, param);
     }
 
-    ret = allocateUTF8(ret);
+    ret = stringToNewUTF8(ret);
     AL.alcStringCache[param] = ret;
     return ret;
   },
@@ -3018,7 +3018,7 @@ var LibraryOpenAL = {
   },
 
   alGetString__proxy: 'sync',
-  alGetString__deps: ['$allocateUTF8'],
+  alGetString__deps: ['$stringToNewUTF8'],
   alGetString: function(param) {
     if (AL.stringCache[param]) {
       return AL.stringCache[param];
@@ -3072,7 +3072,7 @@ var LibraryOpenAL = {
       return 0;
     }
 
-    ret = allocateUTF8(ret);
+    ret = stringToNewUTF8(ret);
     AL.stringCache[param] = ret;
     return ret;
   },

src/library_sdl.js

@@ -1762,10 +1762,10 @@ var LibrarySDL = {
   },
 
   SDL_GetKeyName__proxy: 'sync',
-  SDL_GetKeyName__deps: ['$allocateUTF8'],
+  SDL_GetKeyName__deps: ['$stringToNewUTF8'],
   SDL_GetKeyName: function(key) {
     if (!SDL.keyName) {
-      SDL.keyName = allocateUTF8('unknown key');
+      SDL.keyName = stringToNewUTF8('unknown key');
     }
     return SDL.keyName;
   },
@@ -1817,10 +1817,10 @@ var LibrarySDL = {
   },
 
   SDL_GetError__proxy: 'sync',
-  SDL_GetError__deps: ['$allocateUTF8'],
+  SDL_GetError__deps: ['$stringToNewUTF8'],
   SDL_GetError: function() {
     if (!SDL.errorMessage) {
-      SDL.errorMessage = allocateUTF8("unknown SDL-emscripten error");
+      SDL.errorMessage = stringToNewUTF8("unknown SDL-emscripten error");
     }
     return SDL.errorMessage;
   },
@@ -2185,7 +2185,7 @@ var LibrarySDL = {
     return flags; // We support JPG, PNG, TIF because browsers do
   },
 
-  IMG_Load_RW__deps: ['SDL_LockSurface', 'SDL_FreeRW', '$PATH_FS', 'malloc', '$allocateUTF8'],
+  IMG_Load_RW__deps: ['SDL_LockSurface', 'SDL_FreeRW', '$PATH_FS', 'malloc', '$stringToNewUTF8'],
   IMG_Load_RW__proxy: 'sync',
   IMG_Load_RW: function(rwopsID, freeSrc) {
     try {
@@ -2245,7 +2245,7 @@ var LibrarySDL = {
         if (!raw) {
           if (raw === null) err('Trying to reuse preloaded image, but freePreloadedMediaOnUse is set!');
 #if STB_IMAGE
-          var name = allocateUTF8(filename);
+          var name = stringToNewUTF8(filename);
           addCleanup(function() {
             _free(name);
           });
@@ -3447,15 +3447,15 @@ var LibrarySDL = {
   },
 
   SDL_JoystickName__proxy: 'sync',
-  SDL_JoystickName__deps: ['$allocateUTF8'],
+  SDL_JoystickName__deps: ['$stringToNewUTF8'],
   SDL_JoystickName: function(deviceIndex) {
     var gamepad = SDL.getGamepad(deviceIndex);
     if (gamepad) {
       var name = gamepad.id;
       if (SDL.joystickNamePool.hasOwnProperty(name)) {
         return SDL.joystickNamePool[name];
       }
-      return SDL.joystickNamePool[name] = allocateUTF8(name);
+      return SDL.joystickNamePool[name] = stringToNewUTF8(name);
     }
     return 0;
   },
@@ -3575,9 +3575,9 @@ var LibrarySDL = {
   },
 
   SDL_GetNumAudioDrivers: function() { return 1 },
-  SDL_GetCurrentAudioDriver__deps: ['$allocateUTF8'],
+  SDL_GetCurrentAudioDriver__deps: ['$stringToNewUTF8'],
   SDL_GetCurrentAudioDriver: function() {
-    return allocateUTF8('Emscripten Audio');
+    return stringToNewUTF8('Emscripten Audio');
   },
   SDL_GetScancodeFromKey: function (key) {
     return SDL.scanCodes[key];