.. _ujit-020: |PROJECT| 0.20 Lua API Reference ================================= .. contents:: :local: .. note:: Please note that any function from the list below may be hidden from the end users if sandboxing mechanism is used. Functions --------- ``ujit.coverage.start`` ^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local started = ujit.coverage.start(filename[, excludes]) Starts platform-level coverage counting and streams output to ``filename``. ``excludes`` array with regexps can be optionally passed to exclude filenames from coverage output. Returns ``true`` on success and ``false`` on any error. ``ujit.coverage.stop`` ^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua ujit.coverage.stop() Stops platform-level coverage counting. Does nothing if coverage was not enabled. Does not have a return value. ``ujit.coverage.pause`` ^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua ujit.coverage.pause() Pauses streaming of coverage counting output into file. Does nothing if coverage was not enabled or was already paused. Does not have a return value. ``ujit.coverage.unpause`` ^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua ujit.coverage.unpause() Unpauses streaming of coverage counting output info file. Does nothing if coverage was not enabled or was already unpaused. Does not have a return value. ``ujit.dump.bc`` ^^^^^^^^^^^^^^^^^ .. code-block:: lua ujit.dump.bc(io_object, func) Dumps bytecode of the function ``func`` to ``io_object``. Throws an error if ``io_object`` is not of appropriate type or if ``func`` is not a function. Does not have a return value. ``ujit.dump.bcins`` ^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local dumped = ujit.dump.bcins(io_object, func, pc[, nest_level]) Dumps ``pc``-th bytecode of the function ``func`` to ``io_object``. ``pc`` is 0-based. If ``nest_level`` is specified, prepends the output with corresponding indentation. Throws an error if ``io_object`` is not of appropriate type or if ``func`` is not a function. Returns ``true`` if data was dumped, and ``false`` otherwise. ``ujit.dump.mcode`` ^^^^^^^^^^^^^^^^^^^ .. code-block:: lua ujit.dump.mcode(io_object, trace_no) Dumps machine code for the trace ``trace_no`` to ``io_object``. Throws an error if ``io_object`` is not of appropriate type. Does not have a return value. ``ujit.dump.stack`` ^^^^^^^^^^^^^^^^^^^ .. code-block:: lua ujit.dump.stack(io_object) Dumps the Lua stack of currently executed coroutine to ``io_object``. If any error occurs, dumps nothing. Never throws a run-time error. ``ujit.dump.start`` ^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local started, fname_real = ujit.dump.start([fname_stub]) Starts dumping the progress of the JIT compiler to ``fname_stub`` suffixed with some random extension. ``started`` is set to ``true`` if dumping was started, and ``false`` otherwise. The resulting dump file name is returned to ``fname_real`` if dumping was actually started. If ``fname_stub`` is omitted or passed as ``"-"``, dumping is started to standard output, and ``fname_real`` is set to ``"-"``, too. ``ujit.dump.stop`` ^^^^^^^^^^^^^^^^^^ .. code-block:: lua local stopped = ujit.dump.stop() Stops dumping the progress of the JIT compiler. Returns ``true`` if stop was successful, and ``false`` otherwise. ``ujit.dump.trace`` ^^^^^^^^^^^^^^^^^^^ .. code-block:: lua ujit.dump.trace(io_object, trace_no) Dumps IR for the trace ``trace_no`` to ``io_object``. Throws an error if ``io_object`` is not of appropriate type. Does not have a return value. ``ujit.getmetrics`` ^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local metrics = ujit.getmetrics() Returns a table with the current values of |PROJECT|-specific metrics. The table has following keys: ==================== ================================================================================================ Key Description ==================== ================================================================================================ strnum Current number of ``string`` objects. tabnum Current number of ``table`` objects. udatanum Current number of ``userdata`` objects. gc_total Current number of bytes used by non-sealed objects and all strings (both sealed and non-sealed). gc_sealed Current number of sealed objects excluding strings. gc_freed Number of freed bytes since the last retrieval of metrics. gc_allocated Number of allocated bytes since the last retrieval of metrics. gc_steps_pause Number of GC's ``pause`` phases since the last retrieval of metrics. gc_steps_propagate Number of GC's ``propagate`` phases since the last retrieval of metrics. gc_steps_atomic Number of GC's ``atomic`` phases since the last retrieval of metrics. gc_steps_sweepstring Number of GC's ``sweepstring`` phases since the last retrieval of metrics. gc_steps_sweep Number of GC's ``sweep`` phases since the last retrieval of metrics. gc_steps_finalize Number of GC's ``finalize`` phases since the last retrieval of metrics. jit_snap_restore Number of snapshot restorations since the last retrieval of metrics. strhash_hit Number of hits to the internal string storage since the last retrieval of metrics. strhash_miss Number of misses to the internal string storage since the last retrieval of metrics. ==================== ================================================================================================ ``ujit.immutable`` ^^^^^^^^^^^^^^^^^^ .. code-block:: lua local value = ujit.immutable(value) Makes an object immutable and returns a reference to it for convenience. See :ref:`here ` for details.  ``ujit.memprof.start`` ^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local started, fname_real = ujit.memprof.start(interval, fname_stub) Starts memory profiling for ``interval`` seconds. If ``interval`` is 0, profiling runs until ``ujit.memprof.stop`` is called. Data are streamed to ``fname_stub`` suffixed with some random extension. ``started`` is set to ``true`` if profiling was started, and ``false`` otherwise. Upon successful start, the resulting full profile file name is returned in ``fname_real``. ``ujit.memprof.stop`` ^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local stopped = ujit.memprof.stop() Stops memory profiling started by ``ujit.memprof.start``. Returns ``true`` on success and ``false`` otherwise. ``ujit.profile.available`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local available = ujit.profile.available() Returns ``true`` if |PROJECT|-level profiler is available, and ``false`` otherwise. ``ujit.profile.init`` ^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local initialized = ujit.profile.init() Returns ``true`` if |PROJECT|-level profiler was successfully initialized, and ``false`` otherwise. Profiler cannot be used prior to initialization. ``ujit.profile.start`` ^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local started, fname_real = ujit.profile.start(interval, mode[, fname_stub]) Starts profiling in ``mode`` with sampling ``interval`` (expressed in microseconds). Depending on the ``mode``, may stream profile data to ``fname_stub`` suffixed with some random extension. ``started`` is set to ``true`` if profiling was started, and ``false`` otherwise. The resulting full profile file name is returned in ``fname_real`` if applicable (see below). Supported values for ``mode`` are: =============== ============================================================================================================================================= Value Description =============== ============================================================================================================================================= ``"default"`` Collects only lightweight in-memory per-VM state profile. ``fname_stub`` is ignored, ``fname_real`` is always set to ``nil``. ``"leaf"`` Collects leaf profile. ``fname_stub`` must be specified. If profiling was started, the profile will be streamed to ``fname_real``. ``"callgraph"`` Collects full call-graph profile. ``fname_stub`` must be specified. If profiling was started, the profile will be streamed to ``fname_real``. =============== ============================================================================================================================================= ``ujit.profile.stop`` ^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local counters[, err_reason] = ujit.profile.stop() On success, stops profiling and returns a table with in-memory VM counters. On failure, returns ``nil`` as the first argument and an error reason string as the second argument. ``ujit.profile.terminate`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local terminated = ujit.profile.terminate() Returns ``true`` if |PROJECT|-level profiler was successful terminated, and ``false`` otherwise. Profiler cannot be used after termination. ``ujit.seal`` ^^^^^^^^^^^^^ .. code-block:: lua ujit.seal(obj) Recursively seals ``obj``. Throws a run-time error if sealing could not be finalized. In case of any errors, the state of ``obj`` is guaranteed to be the same as it was prior to the call to this interface. See :ref:`here ` for details.  ``ujit.table.keys`` ^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local new_table = ujit.table.keys(table) Returns a new table with source ``table`` keys as values. Metatable of the table is not copied. Throws a runtime error in case the argument is not a table. Implementation detail (not guaranteed in future versions): Returned table is a sequence. ``ujit.table.shallowcopy`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local new_table = ujit.table.shallowcopy(table) Returns a shallow copy of ``table``. Metatable of the table is not copied. Throws a runtime error in case the argument is not a table. ``ujit.table.toset`` ^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local new_table = ujit.table.toset(table) Returns a new table with source ``table`` values as keys and values set to ``true``. Metatable of the table is not copied. Throws a runtime error in case the argument is not a table.  ``ujit.table.values`` ^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua local new_table = ujit.table.values(table) Returns a new table with source ``table`` values as values. Metatable of the table is not copied. Throws a runtime error in case the argument is not a table. Implementation detail (not guaranteed in future versions): Returned table is a sequence. ``ujit.usesfenv`` ^^^^^^^^^^^^^^^^^ .. code-block:: lua local uses_fenv = ujit.usesfenv(func) Checks if a function ``func`` uses its environment. Following logic applies: - For regular Lua functions, returns ``true`` if the function meets at least one of following conditions (and ``false`` otherwise): - It references at least one global variable. - It references at least one upvalue. - For built-in functions, always returns ``false``. - For registered C functions, always returns ``true``.