4 – программный интерфейс приложений

ENG

4 - Программный интерфейс приложений

 

В этом разделе описывается C API для Lua, то есть набор функций C , доступных для программы хоста для связи с Lua. Все функции API и связанные с ними типы и константы объявлены в файле заголовка lua.h.

Даже когда мы используем Термин «функция», любой объект в API может быть представлена в виде макроса вместо этого. За исключением случаев, когда указано иное, все такие макросы используют каждый из своих аргументов ровно один раз (первый аргумент, который всегда является состояние Lua исключая), и поэтому не создают каких-либо скрытых побочных эффектов.

Как и в большинстве библиотек C, функции API Lua не проверяют свои аргументы в пользу достоверности или согласованности. Тем не менее, вы можете изменить это поведение путем составления Lua с помощью макроса LUA_USE_APICHECKопределенной.

4.1 - Стек

Lua использует виртуальный стек для передачи значений и из C. Каждый элемент в этом стеке представляет значение Lua ( ноль , число, строка и т.д.).

Всякий раз , когда Lua вызовы C, вызываемая функция получает новый стек, который не зависит от предыдущих стеков и стеков функций C ,которые все еще активны. Этот стек изначально содержит какие - либо аргументы функции C , и это где функция C толкает его результаты должны быть возвращены к абоненту (см lua_CFunction).

Для удобства, большинство операций запроса в API не следуют строгой дисциплины стека. Вместо этого они могут обратиться к любому элементу в стеке, используя индекс : Положительный индекс представляет абсолютную позицию стека (начиная с 1); отрицательный индекс представляет собой относительное смещение в верхней части стека. Более конкретно, если стек содержит п элементов, то индекс 1 представляет первый элемент (то есть элемент , который помещается в стек первым) и индекс  п представляет последний элемент; Индекс -1 также представляет последний элемент (то есть, элемент наверху) и индекс -n представляет первый элемент.

4.2 - Размер стека

Когда вы взаимодействовать с API Lua, вы несете ответственность за обеспечение последовательности. В частности, вы несете ответственность за контроль переполнения стека . Вы можете использовать функцию , lua_checkstack чтобы гарантировать , что стек имеет достаточно места для выталкивания новых элементов.

Всякий раз , когда Lua вызовы C, он гарантирует , что стек имеет место , по крайней мере LUA_MINSTACKдополнительных слотов.LUA_MINSTACKОпределяется как 20, так что , как правило , вам не придется беспокоиться о стеке , если ваш код не имеет петли толкающие элементы в стек.

При вызове функции Lua без фиксированного числа результатов (см lua_call), Lua гарантирует , что стек имеет достаточно места для всех результатов, но она не обеспечивает никакого дополнительного пространства. Поэтому, прежде чем что - либо толкая в стеке после такого вызова вы должны использовать lua_checkstack.

4.3 - Допустимые и приемлемые указатели

Любая функция в API , который принимает стека индексов работает только с действительными показателями или приемлемых показателей .

Корректным индексом является индекс , который относится к положению , которое хранит изменяемую значение Lua. Она включает в себя индексы стека между 1 и вершины стека ( 1 ≤ abs(index) ≤ top) плюс псевдо-индексы , которые представляют некоторые позиции, которые доступны для кода C , но которые не находятся в стеке. Псевдо-индексы используются для доступа к реестру (см §4.5 ) и upvalues из функции C (см §4.4 ).

Функции , которые не нуждаются в конкретной изменяемую позицию, а только значение (например, функции запроса), можно назвать с приемлемыми показателями. Приемлемый показатель может быть любой допустимый индекс, но он также может быть любым положительным индексом после вершины стека в пределах пространства , выделенного для стека, то есть индексы до размера стека. (Обратите внимание , что 0 никогда не является приемлемым показателем.) За исключением случаев, когда указано иное, функции в API работы с приемлемыми показателями.

Приемлемые показатели служат, чтобы избежать дополнительных тестов против вершины стека при запросе стека. Например, функция C может запросить свой третий аргумент без необходимости сначала проверить, есть ли третий аргумент, то есть без необходимости проверить 3 является ли допустимым индексом.

Для функций , которые можно назвать с приемлемыми показателями, любой недопустимого индекс рассматривается как если он содержит значение виртуального типа LUA_TNONE, который ведет себя как нулевой стоимости.

4.4 - C Затворы

Когда функция С создается, можно связать несколько значений с ним, создавая при этом замыкание С (см lua_pushcclosure); эти значения называются upvalues и доступны для функции всякий раз , когда она вызывается.

Всякий раз , когда функция C называется, ее upvalues расположены на конкретных псевдо-индексов. Эти псевдо-индексы производятся макроlua_upvalueindex. Первый повышать стоимость , связанная с функцией с индексом lua_upvalueindex(1), и так далее. Любой доступ к , где Nбольше , чем число upvalues функции тока (но не больше , чем 256, который является одним плюс максимальное количество upvalues в затворе), дает приемлемый , но неверный индекс. lua_upvalueindex(n)

4.5 - Реестр

Луа обеспечивает системный реестр , предопределенную таблицу , которая может быть использована любым кодом C хранить любые Луа значения, которые нужны для хранения. В таблице реестра всегда находится в псевдо-индекса LUA_REGISTRYINDEX. Любая библиотека C может хранить данные в эту таблицу, но она должна позаботиться , чтобы выбрать ключи, которые отличаются от тех , которые используются другими библиотеками, чтобы избежать столкновений. Как правило, вы должны использовать в качестве ключа строку , содержащую ваше имя библиотеки, или светло - UserData с адресом объекта C в коде, или любой другой объект Lua , созданный вашим кодом. Как и с именами переменных, строковые ключи , начинающиеся с символа подчеркивания следуют заглавные буквы зарезервированы для Lua.

Целые ключей в реестре используются опорным механизмом (см luaL_ref) и некоторыми предопределенными значениями. Таким образом, целочисленные ключи не должны использоваться для других целей.

При создании нового состояния Lua, его реестра поставляется с некоторыми предопределенными значениями. Эти предопределенные значения индексируются с целыми ключами , определенных как константы в lua.hследующие константы определены.:

  • LUA_RIDX_MAINTHREAD: При этом индекс реестра имеет основной поток государства. (Основной поток является одним созданный совместно с государством.)
  • LUA_RIDX_GLOBALS: В этот индекс в реестре имеет глобальную окружающую среду.

4.6 - Обработка ошибок в C

Внутренне, Lua использует C longjmpсредство для обработки ошибок. (Lua будет использовать исключения , если вы скомпилировать как C ++, поиск LUAI_THROWв исходном коде для деталей.) Когда Lua сталкивается с какой - либо ошибки (например, ошибка выделения памяти, ошибки типа, синтаксические ошибки и ошибки во время выполнения) он вызывает ошибку; то есть, он делает длинный прыжок. Защищенная средаиспользуется setjmp для установки точки восстановления; любая ошибка переходит к самой последней активной точки восстановления.

Если ошибка происходит за пределами какой - либо защищенной среде, Lua вызывает функцию паники (см lua_atpanic) , а затем вызывает abort, таким образом , выход из хост - приложения. Ваша функция паники может избежать этого выхода, никогда не возвращаются (например, делая длинный переход к вашей собственной точки восстановления за пределами Lua).

Функция паники работает как если бы это был обработчик сообщений (см §2.3 ); в частности, объект ошибки находится в верхней части стека. Тем не менее, нет никакой гарантии , о стеке. Для того, чтобы проталкивать что - либо в стеке, функция паники необходимо сначала проверить доступное пространство (см §4.2 ).

Большинство функций в API может вызвать ошибку, например из-за ошибки выделения памяти. Документация для каждой функции указывает на то, может ли она вызывать ошибки.

Внутри функции C вы можете вызвать ошибку путем вызова lua_error.

4.7 - Обработка Урожайность в C

Внутренне, Lua использует C longjmpсредство для получения сопрограмму. Поэтому, если функция C fooвызывает функцию API и эта функция API дает (прямо или косвенно вызывая другую функцию , которая дает), Lua не может вернуться к fooбольше, потому что longjmpудаляет его фрейм из стека C.

Чтобы избежать такого рода проблем, Lua вызывает ошибку всякий раз , когда он пытается дать через вызова API, для трех функций , кроме:lua_yieldk, lua_callk, и lua_pcallk. Все эти функции получают функцию продолжения (как параметр с именем k) , чтобы продолжить выполнение после выхода продукта.

Нам нужно установить некоторую терминологию для объяснения продолжений. У нас есть функция C вызвана из Lua , который мы будем называтьисходную функцию . Эта оригинальная функция затем вызывает одну из этих трех функций в C API, который мы будем называть функцию вызываемого абонента , который затем дает текущий поток. (Это может произойти , когда функция вызываемая lua_yieldk, или когда функция вызываемая либо lua_callkили , lua_pcallk и функция , вызываемая ими выходами.)

Предположим , бегущих выходы потоков во время выполнения функции вызываемого абонента. После того , как поток резюме, он в конечном итоге будет завершить работу функции вызываемого абонента. Тем не менее, функция вызываемая не может вернуться к исходной функции, потому что его кадр в стеке C был разрушен выходом. Вместо этого Lua называет функция продолжения , которая была дана в качестве аргумента функции вызываемого абонента. Как следует из названия, функция продолжения следует продолжить задачу исходной функции.

В качестве примера, рассмотрим следующую функцию:

     int original_function (lua_State *L) {
       ...     /* code 1 */
       status = lua_pcall(L, n, m, h);  /* calls Lua */
       ...     /* code 2 */
     }

Теперь мы хотим , чтобы код Lua время в ведении lua_pcallуступить. Во- первых, мы можем переписать нашу функцию , как здесь:

     int k (lua_State *L, int status, lua_KContext ctx) {
       ...  /* code 2 */
     }
     
     int original_function (lua_State *L) {
       ...     /* code 1 */
       return k(L, lua_pcall(L, n, m, h), ctx);
     }

В приведенном выше коде, новая функция kявляется функцией продолжения (с типом lua_KFunction), который должен делать всю работу , что исходная функция делал после вызова lua_pcall. Теперь мы должны сообщить Lua , что он должен позвонить , kесли код Lua выполняется путемlua_pcallпрерывается каким - то образом (ошибки или получением), поэтому мы переписать код , как здесь, заменив lua_pcallна lua_pcallk:

     int original_function (lua_State *L) {
       ...     /* code 1 */
       return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
     }

Обратите внимание на внешний, явный вызов продолжения: Lua будет вызывать продолжение только при необходимости, то есть, в случае ошибок или возобновления после выхода продукта. Если вызываемая функция возвращает нормально, никогда не получая, lua_pcallklua_callk) также вернется в обычном режиме. (Конечно, вместо того , чтобы вызвать продолжение в этом случае, вы можете сделать равноценную работу непосредственно внутри исходной функции.)

Кроме того, состояние Lua, функция продолжения имеет два других параметра: окончательный статус вызова плюс значение контекста ( ctx) ,который был передан первоначально lua_pcallk. (Lua не использует это значение контекста, он передает только это значение от исходной функции к функции продолжения.) Для получения lua_pcallk, статус одно и то же значение , которое было бы возвращено lua_pcallk, за исключением того, что он , LUA_YIELDкогда выполняется после того, как с выходом (вместо из LUA_OK). Для получения lua_yieldkи lua_callkстатус всегда ,LUA_YIELDкогда Lua вызывает продолжение. (Для этих двух функций, Lua не будет вызывать продолжение в случае возникновения ошибок, потому что они не обрабатывают ошибки.) Кроме того , при использовании lua_callk, вы должны вызвать функцию продолжения с LUA_OKкак статус. (Для получения lua_yieldk, нет особого смысла в вызове непосредственно функцию продолжения, потому что , как lua_yieldkправило , не возвращается.)

Lua рассматривает функцию продолжения , как если бы это была оригинальная функция. Функция продолжения получает тот же стек Lua от исходной функции, в том же состоянии , что было бы , если функция вызываемая вернулась. (Например, после того, как lua_callkфункции и ее аргументы удаляются из стека и заменяются результатами вызова) . Он также имеет те же upvalues. Как бы то ни возвращает обрабатывается Lua ,как если бы это было возвращение исходной функции.

4.8 - Функции и типы

Здесь перечислены все функции и типы из API C в алфавитном порядке. Каждая функция имеет индикатор следующим образом:                                                   [-o, + р, х ]

Первое поле o, это сколько элементов функция выскакивает из стека. Второе поле, pявляется сколько элементов функция толкает в стек. (Любая функция всегда толкает ее результаты после того, как выскакивают свои аргументы.) Поле в форме x|yозначает , что функция может толкать (или поп) xили yэлементы, в зависимости от ситуации; допрос знак ' ?' означает , что мы не можем знать , сколько элементов функция выскакивает / толкает, посмотрев только на своих аргументов (например, они могут зависеть от того, что находится в стеке). Третье поле, xрассказывает , может ли функция поднять ошибки: ' -' означает , что функция никогда не вызывает какую - либо ошибку; ' m' Означает , что функция может поднять вне из памяти ошибок и ошибок , работающих под управлением __gcметаметод; ' e' Означает , что функция может вызвать какие - либо ошибки (он может выполнить произвольный код Lua, либо непосредственно , либо через метаметодами); ' v' Означает , что функция может вызвать ошибку нарочно.

lua_absindex

[-0, +0, -]

int lua_absindex (lua_State *L, int idx);

Преобразует приемлемый индекс idx в эквивалентный абсолютному показателю (то есть, тот , который не зависит от вершины стека).

lua_Alloc

typedef void * (*lua_Alloc) (void *ud,
                             void *ptr,
                             size_t osize,
                             size_t nsize);

Тип функции памяти распределения используемых Lua состояний. Функция распределителем должна обеспечивать функциональность ,аналогичную realloc, но не совсем то же самое. Его аргументы ud, непрозрачный указатель , переданный lua_newstate; ptrуказатель на блок выделяется / перераспределить / освобождены; osize, первоначальный размер блока или какой - то код о том , что выделяется; и nsize, новый размер блока.

Когда ptrнет NULL, osizeявляется размер блока , на который указывает ptr, что есть размер, когда оно было выделено или перераспределены.

Когда ptrэто NULL, osizeкодирует тип объекта , который выделяет Lua. osizeЯвляется любой из LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION,LUA_TUSERDATA, или LUA_TTHREADкогда (и только когда) Lua создает новый объект этого типа. Когда osizeкакое - то другое значение, Lua выделяет память для чего - то другого.

Lua предполагает следующее поведение из функции распределителем:

Когда nsizeравен нулю, то Распределитель должен вести себя , как free и вернуться NULL.

Когда nsizeне равен нулю, распределяющий должен вести себя как realloc. Распределитель возвращается NULL тогда и только тогда , когда он не может выполнить запрос. Lua предполагает , что аллокатор никогда не терпит неудачу , когда osize >= nsize.

Вот простая реализация для функции распределителем. Он используется во вспомогательной библиотеке с помощью luaL_newstate.

     static void *l_alloc (void *ud, void *ptr, size_t osize,
                                                size_t nsize) {
       (void)ud;  (void)osize;  /* not used */
       if (nsize == 0) {
         free(ptr);
         return NULL;
       }
       else
         return realloc(ptr, nsize);
     }

Обратите внимание , что Стандарт C гарантирует , что free(NULL)не имеет никакого эффекта , и что realloc(NULL,size)эквивалентноmalloc(size). Этот код предполагает , что reallocне терпит неудачу , когда сокращается блок. (Хотя стандарт C не обеспечивает такое поведение, по- видимому, является безопасным предположение.)

lua_arith

[- (2 | 1), + 1, е ]

void lua_arith (lua_State *L, int op);

Выполняет арифметические операции или операции побитового над двумя значениями (или один, в случае отрицаний) в верхней части стека, со значением на вершине являющейся второй операнд, поп эти значения, и помещает результат операции. Функция следует семантику соответствующего оператора Lua (то есть, он может назвать метаметодами).

Значение opдолжно быть одним из следующих констант:

  • LUA_OPADD: Выполняет сложение ( +)
  • LUA_OPSUB: Выполняет вычитание ( -)
  • LUA_OPMUL: Выполняет умножение ( *)
  • LUA_OPDIV: Выполняет деление с плавающей точкой ( /)
  • LUA_OPIDIV: Выполняет вольные деление ( //)
  • LUA_OPMOD: Выполняет по модулю ( %)
  • LUA_OPPOW: Выполняет возведение в степень ( ^)
  • LUA_OPUNM: Выполняет математическое отрицание (унарный -)
  • LUA_OPBNOT: Выполняет побитовое НЕ ( ~)
  • LUA_OPBAND: Выполняет побитовое И ( &)
  • LUA_OPBOR: Выполняет побитовое ИЛИ ( |)
  • LUA_OPBXOR: Выполняет побитовое исключающее ИЛИ ( ~)
  • LUA_OPSHL: Выполняет сдвиг влево ( <<)
  • LUA_OPSHR: Выполняет сдвиг вправо ( >>)

lua_atpanic

[-0, +0, -]

lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);

Устанавливает новую функцию паники и возвращает старую (см §4.6 ).

lua_call

[- (nargs + 1), + Nresults, е ]

void lua_call (lua_State *L, int nargs, int nresults);

Вызывает функцию.

Для вызова функции необходимо использовать следующий протокол: во- первых, функция будет называться проталкивается в стек; то, что аргументы функции выталкиваются в прямом порядке; то есть, первый аргумент выталкивается первым. Наконец вы звоните lua_call, nargsэто количество аргументов , которые вы в стек. Все аргументы и значение функции извлекаются из стека , когда функция вызывается. Результаты функции помещаются в стек , когда функция возвращает. Количество результатов , доводят до nresults, если только nresultsне будетLUA_MULTRET. В этом случае все результаты функции выталкиваются. Lua заботится о том , что возвращенные значения вписываются в пространство стека, но это не обеспечивает никакого дополнительного пространства в стеке. Результаты функции помещаются в стек в прямом порядке (первый результат выталкивается первым), так что после вызова последний результат на вершине стека.

Любая ошибка внутри вызываемой функции распространяется вверх (с longjmp).

В следующем примере показано, как программа хоста может сделать эквивалент этому Lua код:

     a = f("how", t.x, 14)

Здесь он находится в C:

lua_getglobal(L, "f");                  /* function to be called */
lua_pushliteral(L, "how");                       /* 1st argument */
lua_getglobal(L, "t");                    /* table to be indexed */
lua_getfield(L, -1, "x");        /* push result of t.x (2nd arg) */
lua_remove(L, -2);                  /* remove 't' from the stack */
lua_pushinteger(L, 14);                          /* 3rd argument */
lua_call(L, 3, 1);     /* call 'f' with 3 arguments and 1 result */
lua_setglobal(L, "a");                         /* set global 'a' */

Обратите внимание , что приведенный выше код является сбалансированным : в его конце стек возвращается к своей первоначальной конфигурации. Это считается хорошей практикой программирования.

lua_callk

[- (nargs + 1), + Nresults, е ]

void lua_callk (lua_State *L,
                int nargs,
                int nresults,
                lua_KContext ctx,
                lua_KFunction k);

Эта функция ведет себя так же , как lua_call, но позволяет называемую функцию , чтобы получить (см §4.7 ).

lua_CFunction

typedef int (*lua_CFunction) (lua_State *L);

Введите для функций C.

Для того , чтобы должным образом взаимодействовать с Lua, функция C должна использовать следующий протокол, который определяет путь параметры и результаты передаются: функция C получает свои аргументы из Lua в стеке в прямом порядке (первый аргумент выталкивается первым). Таким образом, при запуске функции, lua_gettop(L)возвращает количество аргументов , полученных с помощью функции. Первый аргумент (если таковые имеются) с индексом 1 , а его последний аргумент в индексе lua_gettop(L). Для возврата значений в Lua, функция C просто толкает их в стек, в прямом порядке (первый результат помещается в первую очередь), и возвращает количество результатов. Любое другое значение в стеке ниже результатов будет правильно отбрасываются Lua. Подобно функции Lua, функция C вызывается Lua также может возвращать много результатов.

В качестве примера, следующая функция получает переменное число числовых аргументов и возвращает их среднее значение и их сумму:

     static int foo (lua_State *L) {
       int n = lua_gettop(L);    /* number of arguments */
       lua_Number sum = 0.0;
       int i;
       for (i = 1; i <= n; i++) {
         if (!lua_isnumber(L, i)) {
           lua_pushliteral(L, "incorrect argument");
           lua_error(L);
         }
         sum += lua_tonumber(L, i);
       }
       lua_pushnumber(L, sum/n);        /* first result */
       lua_pushnumber(L, sum);         /* second result */
       return 2;                   /* number of results */
     }

lua_checkstack

[-0, +0, -]

int lua_checkstack (lua_State *L, int n);

Обеспечивает , что стек имеет место , по крайней мере , nдополнительные слоты (то есть, что вы можете спокойно нажать до nзначений в него). Она возвращает ложь , если она не может выполнить запрос, либо потому , что это вызвало бы стек быть больше установленного максимального размера ( как правило , по меньшей мере , несколько тысяч элементов) или потому , что он не может выделить память для дополнительного пространства. Эта функция никогда не сжимает стек; если стек уже имеется пространство для дополнительных слотов, он остается неизменным.

lua_close

[-0, +0, -]

void lua_close (lua_State *L);

Уничтожает все объекты в заданном состоянии Lua (вызов соответствующих метаметодами сборки мусора, если таковые имеются) и освобождает всю динамическую память, используемую этим государством. На нескольких платформах, вам не нужно вызывать эту функцию, потому что все ресурсы естественно освобождены, когда заканчивается программа хоста. С другой стороны, долго работающие программы, которые создают несколько состояний, таких как демоны или веб-серверов, вероятно, потребуется закрыть государства, как только они не нужны.

lua_compare

[-0, +0, e]

int lua_compare (lua_State *L, int index1, int index2, int op);

Сравнивает два значения Lua. Возвращает 1 , если значение с индексом index1удовлетворяет op по сравнению со значением на индекс index2, следуя семантикой соответствующего оператора Lua (то есть, он может назвать метаметодами). В противном случае возвращает 0. Также возвращает 0 , если любой из индексов не является действительным.

Значение opдолжно быть одним из следующих констант:

  • LUA_OPEQ: Сравнивает равенство ( ==)
  • LUA_OPLT: Сравнивает менее ( <)
  • LUA_OPLE: Сравнивает меньше или равно ( <=)

lua_concat

[-n, +1, е ]

void lua_concat (lua_State *L, int n);

Сцепляются nзначения в вершине стека, поп их, и оставляет результат на самом верху. Если n равен 1, то результатом будет одно значение в стеке (то есть, функция ничего не делает); если nравен 0, то результатом является пустая строка. Конкатенация выполняется , следуя обычной семантики Lua (см §3.4.6 ).

lua_copy

[-0, +0, -]

void lua_copy (lua_State *L, int fromidx, int toidx);

Копии элемента с индексом fromidx в допустимый индекс toidx, заменив значение в этой позиции. Значения в других местах, не затрагиваются.

lua_createtable

[-0, +1, m ]

void lua_createtable (lua_State *L, int narr, int nrec);

Создает новую пустую таблицу и помещает его в стек. Параметр , narrнамек на сколько элементов таблицы будет иметь как последовательность;Параметр nrecявляется подсказкой для того, как многие другие элементы таблицы будут иметь. Lua может использовать эти подсказки , чтобы предварительно выделить память для новой таблицы. Это preallocation полезно для производительности , когда вы заранее знаете , сколько элементов таблица будет иметь. В противном случае вы можете использовать функцию lua_newtable.

lua_dump

[-0, +0, -]

int lua_dump (lua_State *L,
                        lua_Writer writer,
                        void *data,
                        int strip);

Сплин функцию в виде двоичного фрагмента. Получает функцию Lua на вершине стека и создает двоичный кусок , который, если он загружен снова, приводит к функции , эквивалентной одному сбрасывали. Как она производит части куска, lua_dumpвызывает функцию writer(см lua_Writer) с заданным data записать их.

Если stripэто верно, то бинарное представление не может включать в себя все отладить информацию о функции, для экономии места.

Значение, которое возвращает код ошибки, возвращаемый последнего вызова писателя; 0 означает отсутствие ошибок.

Эта функция не совать функцию Lua из стека.

lua_error

[-1, +0, v]

int lua_error (lua_State *L);

Генерирует ошибку Lua, используя значение в верхней части стека в качестве объекта ошибки. Эта функция не делает длинный прыжок, и ,следовательно , никогда не возвращается (см luaL_error).

lua_gc

[-0, +0, e ]

int lua_gc (lua_State *L, int what, int data);

Управляет сборщик мусора.

Эта функция выполняет несколько задач, в соответствии со значением параметра what:

  • LUA_GCSTOP: Останавливает сборщик мусора.
  • LUA_GCRESTART: Перезапускает сборщик мусора.
  • LUA_GCCOLLECT: Выполняет полный цикл сборки мусора.
  • LUA_GCCOUNT: Возвращает текущий объем памяти (в килобайтах) в использовании с помощью Lua.
  • LUA_GCCOUNTB: Возвращает остаток от деления текущего количества байтов памяти, используемой Lua на 1024.
  • LUA_GCSTEP: Выполняет приращении сборки мусора.
  • LUA_GCSETPAUSE: Устанавливает в dataкачестве нового значения для паузы коллектора (см п.2.5 ) и возвращает предыдущее значение паузы.
  • LUA_GCSETSTEPMUL: Устанавливает в dataкачестве нового значения для шага множителя коллектора (см п.2.5 ) и возвращает предыдущее значение шага множителя.
  • LUA_GCISRUNNING: Возвращает логическое , который говорит , работает ли коллектор (т.е. не прекращался).

Более подробную информацию об этих параметрах см collectgarbage.

lua_getallocf

[-0, +0, -]

lua_Alloc lua_getallocf (lua_State *L, void **ud);

Возвращает функцию памяти о выделении данного государства. Если udнет NULL, Lua сохраняет в *udнепрозрачный указатель дается , когда функция памяти аллокатор была установлена.

lua_getfield

[-0, +1, e ]

int lua_getfield (lua_State *L, int index, const char *k);

Помещает в стек величина t[k], где tэто значение по данному индексу. Как и в Lua, эта функция может вызвать метаметод для "индекса" событие (см п.2.4 ).

Возвращает тип толкаемого значения.

lua_getextraspace

[-0, +0, -]

void *lua_getextraspace (lua_State *L);

Возвращает указатель на сырьевой области памяти, связанной с данным состоянием Lua. Приложение может использовать эту область для любых целей; Lua не использует его для чего-нибудь.

Каждый новый поток имеет эту область инициализированному с копией области основного потока.

По умолчанию, эта область имеет размер указателя на пустоту, но вы можете перекомпилировать Lua с разного размера для этой области. (СмLUA_EXTRASPACEв luaconf.h.)

lua_getglobal

[-0, +1, e ]

int lua_getglobal (lua_State *L, const char *name);

Помещает в стек значение глобальной name. Возвращает тип этого значения.

lua_geti

[-0, +1, e ]

int lua_geti (lua_State *L, int index, lua_Integer i);

Помещает в стек величина t[i], где tэто значение по данному индексу. Как и в Lua, эта функция может вызвать метаметод для "индекса" событие (см п.2.4 ).

Возвращает тип толкаемого значения.

lua_getmetatable

[= 0, + (0 | 1), -]

int lua_getmetatable (lua_State *L, int index);

Если значение в данном индексе имеет метатаблицу, функция толкает эту метатаблицу в стек и возвращает 1. В противном случае функция возвращает 0 и не толкает ничего в стеке.

lua_gettable

[-1, +1, e ]

int lua_gettable (lua_State *L, int index);

Помещает в стек величина t[k], где tэто значение по данному индексу и kявляется значением на вершине стека.

Эта функция выталкивает ключ из стека, толкая полученное значение на своем месте. Как и в Lua, эта функция может вызвать метаметод для "индекса" событие (см п.2.4 ).

Возвращает тип толкаемого значения.

lua_gettop

[-0, +0, -]

int lua_gettop (lua_State *L);

Возвращает индекс верхнего элемента в стеке. Поскольку индексы начинаются с 1, этот результат равен числу элементов в стеке; в частности, 0 означает пустой стек.

lua_getuservalue

[-0, +1, -]

int lua_getuservalue (lua_State *L, int index);

Помещает в стек значение Lua, связанное с UserData по данному индексу.

Возвращает тип толкаемого значения.

lua_insert

[-1, +1, -]

void lua_insert (lua_State *L, int index);

Перемещает верхний элемент в заданный допустимый индекс, сдвигая вверх элементов выше этого показателя, чтобы открыть пространство. Эта функция не может быть вызвана с псевдо-индексом, так как псевдо-индекс не является фактическое положение стека.

lua_Integer

typedef ... lua_Integer;

Тип целых чисел в Lua.

По умолчанию этот тип long long, ( как правило, 64-разрядные два комплемента целое число), но это может быть изменено на longили int ( какправило, 32-разрядные два комплемента целое число). (См LUA_INT_TYPEв luaconf.h.)

Lua также определяет константы LUA_MININTEGERи LUA_MAXINTEGERс минимальными и максимальными значениями , которые соответствуют в этом типе.

lua_isboolean

[-0, +0, -]

int lua_isboolean (lua_State *L, int index);

Возвращает 1, если значение по данному индексу является логическим, и 0 в противном случае.

lua_iscfunction

[-0, +0, -]

int lua_iscfunction (lua_State *L, int index);

Возвращает 1, если значение по данному индексу является функцией C, и 0 в противном случае.

lua_isfunction

[-0, +0, -]

int lua_isfunction (lua_State *L, int index);

Возвращает 1, если значение по данному индексу является функцией (С или Lua), и 0 в противном случае.

lua_isinteger

[-0, +0, -]

int lua_isinteger (lua_State *L, int index);

Возвращает 1, если значение по данному индексу является целым числом (то есть, значение является числом и представляется как целое число), и 0 в противном случае.

lua_islightuserdata

[-0, +0, -]

int lua_islightuserdata (lua_State *L, int index);

Возвращает 1, если значение по данному индексу является легким UserData, и 0 в противном случае.

lua_isnil

[-0, +0, -]

int lua_isnil (lua_State *L, int index);

Возвращает 1 , если значение по данному показателю является ноль , и 0 в противном случае.

lua_isnone

[-0, +0, -]

int lua_isnone (lua_State *L, int index);

Возвращает 1, если данный показатель не является действительным, и 0 в противном случае.

lua_isnoneornil

[-0, +0, -]

int lua_isnoneornil (lua_State *L, int index);

Возвращает 1 , если данный показатель не является действительным , или если значение по этому показателю является ноль , и 0 в противном случае.

lua_isnumber

[-0, +0, -]

int lua_isnumber (lua_State *L, int index);

Возвращает 1, если значение по данному индексу является числом или строкой, конвертируемой в число, и 0 в противном случае.

lua_isstring

[-0, +0, -]

int lua_isstring (lua_State *L, int index);

Возвращает 1, если значение по данному индексу является строка или число (которое всегда конвертируются в строку), и 0 в противном случае.

lua_istable

[-0, +0, -]

int lua_istable (lua_State *L, int index);

Возвращает 1, если значение по данному индексу представляет собой таблицу, и 0 в противном случае.

lua_isthread

[-0, +0, -]

int lua_isthread (lua_State *L, int index);

Возвращает 1, если значение по данному индексу является поток, и 0 в противном случае.

lua_isuserdata

[-0, +0, -]

int lua_isuserdata (lua_State *L, int index);

Возвращает 1, если значение по данному индексу является UserData (или на полный свет), и 0 в противном случае.

lua_isyieldable

[-0, +0, -]

int lua_isyieldable (lua_State *L);

Возвращает 1, если данная сопрограммная может уступить, и 0 в противном случае.

lua_KContext

typedef ... lua_KContext;

Типа для продолжения-функциональных контекстах. Это должен быть числовой тип. Этот тип определяется как intptr_t если intptr_tдоступно, так что он может хранить указатели тоже. В противном случае она определяется как ptrdiff_t.

lua_KFunction

typedef int(*lua_KFunction)(lua_State *L,int status,lua_KContext ctx);

Тип для функций продолжения (см §4.7 ).

lua_len

[-0, +1, ]

void lua_len (lua_State *L, int index);

Возвращает длину значения по данному индексу. Это эквивалентно ' #' оператора в Lua (см §3.4.7 ) и может вызвать метаметод для «длины» события (см п.2.4 ). Результат помещается в стек.

lua_load

[-0, +1, -]

int lua_load (lua_State *L,
              lua_Reader reader,
              void *data,
              const char *chunkname,
              const char *mode);

Загружает кусок Lua , не запуская ее. Если ошибок нет, lua_load толкает скомпилированный кусок как функцию Lua на вершине стека. В противном случае, он толкает сообщение об ошибке.

Возвращаемые значения lua_loadявляются:

  • LUA_OK Не: никаких ошибок;
  • LUA_ERRSYNTAX: Ошибка синтаксиса при прекомпиляции;
  • LUA_ERRMEM: Выделение памяти (из- за нехватки памяти) ошибок;
  • LUA_ERRGCMM: Ошибка при запуске __gcметаметод. (Эта ошибка не имеет никакого отношения куска загружается. Он генерируется сборщиком мусора.)

lua_load Функция использует предоставленный пользователем readerфункцию , чтобы прочитать кусок (см lua_Reader). data Аргумент является непрозрачным значение передается функции считывателя.

chunkname Аргумент дает название фрагмента, который используется для сообщений об ошибках и отладки информации (см §4.9 ).

lua_load автоматически определяет , является ли фрагмент текстовым или двоичным и загружает его соответствующим образом (см программуluac). Строка modeработает как в функции load, с добавлением , что NULLзначение эквивалентно строке " bt".

lua_load использует стек внутри, поэтому функция читатель должен всегда оставлять стек неизмененной при возвращении.

Если полученная функция имеет upvalues, его первый повышать стоимость устанавливается на значение глобальной окружающей среды ,хранящейся в индексе LUA_RIDX_GLOBALSв реестре (см §4.5 ). При загрузке основных кусками, это будет повышать стоимость _ENVпеременной (см§2.2 ). Другие upvalues инициализируются с нуля .

lua_newstate

[-0, +0, -]

lua_State *lua_newstate (lua_Alloc f, void *ud);

Создает новую нить , которая проходит в новом, независимом государстве. Возвращает , NULLесли он не может создать нить или состояние (из - за нехватки памяти). Аргумент fявляется функцией распределителем; Lua делает все выделения памяти для этого состояния с помощью этой функции. Второй аргумент ud, является непрозрачным указатель , который Lua переходит к распределителю в каждом вызове.

lua_newtable

[-0, +1, m ]

void lua_newtable (lua_State *L);

Создает новую пустую таблицу и помещает его в стек. Это эквивалентно lua_createtable(L, 0, 0).

lua_newthread

[-0, +1, m ]

lua_State *lua_newthread (lua_State *L);

Создает новый поток, толкает его в стек, и возвращает указатель на lua_Stateкоторый представляет эту новую нить. Новый поток , возвращаемый этой функцией акций с оригиналом нить свою глобальную окружающую среду, но имеет отдельный стек выполнения.

Там нет явной функции, чтобы закрыть или уничтожить нить. Темы подлежат сбору мусора, как и любой объект Lua.

lua_newuserdata

[-0, +1, m ]

void *lua_newuserdata (lua_State *L, size_t size);

Эта функция выделяет новый блок памяти с заданного размера, толкает в стек новый полный UserData с адреса блока, и возвращает этот адрес.Хост-программа может свободно использовать эту память.

lua_next

[-1, + (2 | 0), е ]

int lua_next (lua_State *L, int index);

Забирает ключ из стека, и толкает пару ключ-значение из таблицы по заданному индексу ( "следующий" после того, как пара данного ключа). Если нет больше элементов в таблице, а затем lua_nextвозвращает 0 (и не толкает ничего).

Типичная обходом выглядит следующим образом:

     /* table is in the stack at index 't' */
     lua_pushnil(L);  /* first key */
     while (lua_next(L, t) != 0) {
       /* uses 'key' (at index -2) and 'value' (at index -1) */
       printf("%s - %s\n",
              lua_typename(L, lua_type(L, -2)),
              lua_typename(L, lua_type(L, -1)));
       /* removes 'value'; keeps 'key' for next iteration */
       lua_pop(L, 1);
     }

В то время прохождения таблицы, не называйте lua_tolstring непосредственно на ключе, если вы не знаете , что ключ на самом деле является строкой. Напомним , что lua_tolstring может изменить значение по данному индексу; это сбивает с толку следующий вызов lua_next.

См функцию nextдля предостережений изменения таблицы во время ее обхода.

lua_Number

typedef ... lua_Number;

Тип поплавков в Lua.

По умолчанию этот тип двойной, но который может быть изменен на один поплавок или длинный двойник. (См LUA_FLOAT_TYPEв luaconf.h.)

lua_numbertointeger

int lua_numbertointeger (lua_Number n, lua_Integer *p);

Преобразует поплавка Lua в целое число Lua. Этот макрос предполагает , что nимеет интегральное значение. Если это значение находится впределах диапазона Lua целых чисел, он преобразуется в целое число и назначается *p. Макрос приводит логическое значение , указывающее ,был ли преобразование успешным. (Обратите внимание , что этот тест диапазон может быть сложно сделать правильно , без этого макроса, в связи с округлением.)

Этот макрос может оценивать его аргументы более чем один раз.

lua_pcall

[- (nargs + 1), + (nresults | 1), -]

int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);

Вызывает функцию в защищенном режиме.

Оба nargsи nresultsимеют тот же смысл, что и в lua_call. Если нет никаких ошибок во время вызова, lua_pcallведет себя точно как lua_call.Тем не менее, если есть какая - либо ошибка, lua_pcallловит его, толкает одно значение в стеке (объект ошибки), и возвращает код ошибки. Какlua_call, lua_pcallвсегда удаляет функцию и ее аргументы из стека.

Если msghравно 0, то объект возвращается ошибка в стеке именно исходный объект ошибки. В противном случае, msghэто индекс стека изобработчика сообщений . (Этот показатель не может быть псевдо-индекс.) В случае возникновения ошибки во время выполнения, то эта функция будет вызвана с объектом ошибки и ее возвращаемое значение будет объект возвращается в стек lua_pcall.

Как правило, обработчик сообщений используется для добавления дополнительной информации отладки для объекта ошибки, такие как стек TRACEBACK. Такая информация не может быть собрана после возвращения lua_pcall, так как к этому времени стек раскручивается.

lua_pcall Функция возвращает одно из следующих констант (определенных в lua.h):

  • LUA_OK(0): успех.
  • LUA_ERRRUN: Ошибка во время выполнения.
  • LUA_ERRMEM: Ошибка распределения памяти. Для таких ошибок, Lua не вызывает обработчик сообщений.
  • LUA_ERRERR: Ошибка при выполнении обработчика сообщений.
  • LUA_ERRGCMM: Ошибка при запуске __gcметаметод. (Эта ошибка , как правило,                           не имеет никакого отношения к вызываемой функции.)

lua_pcallk

[- (nargs + 1), + (nresults | 1), -]

int lua_pcallk (lua_State *L,
                int nargs,
                int nresults,
                int msgh,
                lua_KContext ctx,
                lua_KFunction k);

Эта функция ведет себя так же , как lua_pcall, но позволяет называемую функцию , чтобы получить (см §4.7 ).

lua_pop

[-n, +0, -]

недействительным lua_pop (lua_State * L, Int N);

Забирает nэлементы из стека.

lua_pushboolean

[-0, +1, -]

void lua_pop (lua_State *L, int n);

Заносит логическое значение со значением bв стек.

lua_pushcclosure

[-n, +1, т ]

void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);

Заносит новое замыкание C в стек.

Когда функция С создается, можно связать несколько значений с ним, создавая , таким образом , замыкание C (см §4.4 ); эти значения затем доступны функции всякий раз , когда она вызывается. Чтобы связать значения с функцией C, сначала эти значения должны быть в стек (при наличии нескольких значений, первое значение выталкивается первым). Затем lua_pushcclosure вызывается для создания и нажать функцию C в стек, с аргументом , nсообщая , сколько значений будет связан с функцией. lua_pushcclosure Также выводит эти значения из стека.

Максимальное значение nравно 255.

Когда nравен нулю, то эта функция создает функцию света C , который является только указателем на функцию C. В этом случае, он никогда не вызывает ошибку памяти.

lua_pushcfunction

[-0, +1, -]

void lua_pushcfunction (lua_State *L, lua_CFunction f);

Помещает функцию C в стек. Эта функция получает указатель на функцию C и толкает в стек значение Lua типа , functionчто, при вызове, вызывает соответствующую функцию C.

Любая функция быть отозваны с помощью Lua должны следовать правильный протокол , чтобы получить его параметры и возвращать его результаты (см lua_CFunction).

lua_pushfstring

[-0, +1, m ]

const char *lua_pushfstring (lua_State *L, const char *fmt, ...);

Помещает в стек отформатированную строку и возвращает указатель на эту строку. Она аналогична функции ISO C sprintf, но имеет несколько важных отличий:

  • Вы не должны выделить пространство для результата: результат является строкой Lua и Lua заботится о распределении памяти (и освобождения памяти, путем сбора мусора).
  • Типы преобразования довольно ограничены. Там нет никаких флагов, ширины или Precisions. Спецификаторы преобразования может быть только ' %%' (вставляет символ ' %'), ' %s' (вставляет завершается нулем строку, без каких - либо ограничений размера), ' %f' (вставляетlua_Number), ' %I' (Вставляет lua_Integer), ' %p' (вкладыши указатель как шестнадцатеричное число), ' %d' (вставляет int), ' %c' (вставляет intв один байт символа а), а ' %U' (вставляет long intкак последовательность байтов UTF-8).

В отличие от других функций толчка, эта функция проверяет для стека он нуждается, в том числе и слот для ее результата.

lua_pushglobaltable

[-0, +1, -]

void lua_pushglobaltable (lua_State *L);

Заносит глобальной окружающей среды в стек.

lua_pushinteger

[-0, +1, -]

void lua_pushinteger (lua_State *L, lua_Integer n);

Помещает целое число со значением nв стек.

lua_pushlightuserdata

[-0, +1, -]

void lua_pushlightuserdata (lua_State *L, void *p);

Заносит легкую UserData в стек.

Userdata представляют значения C в Lua. Свет UserData представляет собой указатель, A void*. Это значение (как число): вы не создаете его, он не имеет отдельного метатаблицу, и он не собирается (как он никогда не был создан). Свет UserData равно "любой" легкий UserData с тем же адресом C.

lua_pushliteral

[-0, +1, m ]

const char *lua_pushliteral (lua_State *L, const char *s);

Этот макрос эквивалентен lua_pushstring, но их следует использовать только тогда , когда sэто символьная строка.

lua_pushlstring

[-0, +1, m ]

const char *lua_pushlstring (lua_State *L, const char *s, size_t len);

Выталкивает строку , указанную sс размером len в стек. Lua делает (или повторно) внутреннюю копию данной строки, так что память у sможет быть освобождена или повторно сразу после завершения функции. Строка может содержать любые двоичные данные, включая вложенные нули.

Возвращает указатель на внутреннюю копию строки.

lua_pushnil

[-0, +1, -]

void lua_pushnil (lua_State *L);

Помещает ноль значение в стек.

lua_pushnumber

[-0, +1, -]

void lua_pushnumber (lua_State *L, lua_Number n);

Помещает поплавок со значением nв стек.

lua_pushstring

[-0, +1, m ]

const char *lua_pushstring (lua_State *L, const char *s);

Выталкивает нулем строку , указанную s в стек. Lua делает (или повторно) внутреннюю копию данной строки, так что память у sможет быть освобождена или повторно сразу после завершения функции.

Возвращает указатель на внутреннюю копию строки.

Если sесть NULL, толкает ноль и возвращается NULL.

lua_pushthread

[-0, +1, -]

int lua_pushthread (lua_State *L);

Помещает нить , представленную Lна стек. Возвращает 1 , если этот поток основной поток его состояния.

lua_pushvalue

[-0, +1, -]

void lua_pushvalue (lua_State *L, int index);

Помещает копию элемента по данному индексу в стек.

lua_pushvfstring

[-0, +1, m ]

const char *lua_pushvfstring (lua_State *L,
                              const char *fmt,
                              va_list argp);

Эквивалент lua_pushfstring, за исключением того, что он получает va_list вместо переменного числа аргументов.

lua_rawequal

[-0, +0, -]

int lua_rawequal (lua_State *L, int index1, int index2);

Возвращает 1 , если два значения в индексах index1и index2примитивно равны (то есть без вызова __eqметаметод). В противном случае возвращает 0. возвращает также значение 0 , если любой из индексов не являются действительными.

lua_rawget

[-1, +1, -]

int lua_rawget (lua_State *L, int index);

Аналогично lua_gettable, но делает сырой доступ (т.е. без метаметодами).

lua_rawgeti

[-0, +1, -]

int lua_rawgeti (lua_State *L, int index, lua_Integer n);

Помещает в стек величина t[n], где tнаходится таблица по данному индексу. Доступ в сыром виде , то есть, он не вызывается __indexметаметод.

Возвращает тип толкаемого значения.

lua_rawgetp

[-0, +1, -]

int lua_rawgetp (lua_State *L, int index, const void *p);

Помещает в стек величина t[k], где tнаходится таблица с указанным индексом и kявляется указателем pпредставлен в виде светло - UserData.Доступ сырой; то есть, он не вызывается __indexметаметод.

Возвращает тип толкаемого значения.

lua_rawlen

[-0, +0, -]

size_t lua_rawlen (lua_State *L, int index);

Возвращает сырой "длину" значения по данному индексу: для строк, это длина строки; для таблиц, это результат оператора длины ( ' #') без метаметодами; для UserData, это размер блока памяти , выделенной для UserData; для других значений, то 0.

lua_rawset

[-2, + 0, т ]

void lua_rawset (lua_State *L, int index);

Аналогично lua_settable, но делает сырое назначение (т.е. без метаметодами).

lua_rawseti

[-1, +0, m ]

void lua_rawseti (lua_State *L, int index, lua_Integer i);

Есть ли эквивалент t[i] = v, где tнаходится таблица с указанным индексом и vявляется значением на вершине стека.

Эта функция выталкивает значение из стека. Отнесение сырой, то есть, он не вызывается __newindexметаметод.

lua_rawsetp

[-1, +0, m ]

void lua_rawsetp (lua_State *L, int index, const void *p);

Есть ли эквивалент t[p] = v, где tприводится таблица по данному индексу, pкодируется в виде светло - UserData, и vэто значение на вершине стека.

Эта функция выталкивает значение из стека. Отнесение сырой, то есть, он не вызывает __newindexметаметод.

lua_Reader

typedef const char * (*lua_Reader) (lua_State *L,
                                    void *data,
                                    size_t *size);

Функция используется для чтения lua_load. Каждый раз , когда он нуждается в другой кусок кусок, lua_loadвызывает читателя, проходя вдоль егоdataпараметра. Читатель должен возвращать указатель на блок памяти с новой частью порции и установить sizeна размер блока. Блок должен существовать , пока функция читатель не вызывается снова. Для того, чтобы обозначить конец фрагмента, читатель должен вернуть NULLили установить sizeна ноль. Функция читатель может возвращать части любого размера больше нуля.

lua_register

[-0, +0, e ]

void lua_register (lua_State *L, const char *name, lua_CFunction f);

Устанавливает функцию C в fкачестве нового значения глобального name. Она определяется как макрос:

     #define lua_register(L,n,f) \
            (lua_pushcfunction(L, f), lua_setglobal(L, n))

lua_remove

[-1, +0, -]

void lua_remove (lua_State *L, int index);

Удаляет элемент в заданном допустимый индекс, сдвигая вниз выше этого индекса элементов, чтобы заполнить этот пробел. Эта функция не может быть вызвана с псевдо-индексом, так как псевдо-индекс не является фактическое положение стека.

lua_replace

[-1, +0, -]

void lua_replace (lua_State *L, int index);

Перемещает верхний элемент в данной допустимый индекс без смещения любого элемента (поэтому заменяя значение, при этом данный индекс), а затем выталкивает верхний элемент.

lua_resume

[- ?, + ?, -]

int lua_resume (lua_State *L, lua_State *from, int nargs);

Запускает и возобновляет сопрограмму в данной теме L.

Чтобы начать сопрограмму, вы нажимаете на нить стек главную функцию плюс любые аргументы; то вы звоните lua_resume, с nargsявляется числом аргументов. Этот вызов возвращает , когда сопрограммная приостанавливает или заканчивает исполнение. Когда он возвращается, стек содержит все значения , передаваемые lua_yieldили все значения , возвращенные функцией тела. lua_resumeВозвращается , LUA_YIELDесли доходность сопрограмма, LUA_OKесли сопрограммная заканчивает исполнение без ошибок, или код ошибки в случае ошибок (см lua_pcall).

В случае ошибок, стек не сматывается, так что вы можете использовать отладочный API над ним. Объект ошибки находится на вершине стека.

Чтобы возобновить сопрограмму, удалите все результаты последнего lua_yield, поставить на его стек только значения , которые будут переданы вкачестве результатов yield, а затем вызвать lua_resume.

Параметр fromпредставляет собой сопрограмму , который докачку L. Если нет такой сопрограммная, этот параметр может быть NULL.

lua_rotate

[-0, +0, -]

void lua_rotate (lua_State *L, int idx, int n);

Поворачивает элементы стека между действительным индексом idx и в верхней части стека. Элементы вращаны nпозиции в направлении верхней части, для положительного nили -nпозиции в направлении нижней части, для отрицательного n. Абсолютное значение nне должно быть больше ,чем размер среза поворота. Эта функция не может быть вызвана с псевдо-индексом, так как псевдо-индекс не является фактическое положение стека.

lua_setallocf

[-0, +0, -]

void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);

Изменение функции распределителем данного государства f с пользовательскими данными ud.

lua_setfield

[-1, +0, e ]

void lua_setfield (lua_State *L, int index, const char *k);

Есть ли эквивалент t[k] = v, где это значение по данному индексу и является значением на вершине стека.

Эта функция выталкивает значение из стека. Как и в Lua, эта функция может вызвать метаметод для "NewIndex" событие (см п.2.4 ).

lua_setglobal

[-1, +0, e ]

void lua_setglobal (lua_State *L, const char *name);

Забирает значение из стека и устанавливает его в качестве нового значения глобального name.

lua_seti

[-1, +0, e ]

void lua_seti (lua_State *L, int index, lua_Integer n);

Есть ли эквивалент t[n] = v, где tэто значение по данному индексу и vявляется значением на вершине стека.

Эта функция выталкивает значение из стека. Как и в Lua, эта функция может вызвать метаметод для "NewIndex" событие (см п.2.4 ).

lua_setmetatable

[-1, +0, -]

недействительным lua_setmetatable (lua_State * L, INT индекс);

Забирает таблицу из стека и устанавливает его в качестве нового метатаблицы для значения по данному индексу.

lua_settable

[-2, + 0, е ]

void lua_settable (lua_State *L, int index);

Есть ли эквивалент t[k] = v, где tэто значение по данному индексу, vэто значение на вершине стека, и kэто значение чуть ниже вершины.

Эта функция появляется как ключ и значение из стека. Как и в Lua, эта функция может вызвать метаметод для "NewIndex" событие (см п.2.4 ).

lua_settop

[- ?, + ?, -]

void lua_settop (lua_State *L, int index);

Принимает любой индекс, или 0, и устанавливает вершины стека этому показателю. Если новая вершина больше , чем старая, то новые элементы заполнены нолю . Если indexравно 0, то все элементы стека удаляются.

lua_setuservalue

[-1, +0, -]

void lua_setuservalue (lua_State *L, int index);

Забирает значение из стека и устанавливает его в качестве нового значения, связанного с UserData по данному индексу.

lua_State

typedef struct lua_State lua_State;

Непрозрачная структура, которая указывает на нить и косвенно (через нити) в целом состояние интерпретатора Lua. Библиотека Lua полностью реентерабельным: он не имеет глобальных переменных. Вся информация о состоянии доступна через эту структуру.

Указатель на эту структуру должны быть переданы в качестве первого аргумента для каждой функции в библиотеке, за исключением тогоlua_newstate, что создает состояние Lua с нуля.

lua_status

[-0, +0, -]

int lua_status (lua_State *L);

Возвращает состояние нити L.

Статус может быть 0 ( LUA_OK) для нормального потока, код ошибки , если нить завершила выполнение lua_resumeс ошибкой, или LUA_YIELDесли поток приостанавливается.

Вы можете только вызывать функции в потоках со статусом LUA_OK. Вы можете возобновить темы со статусом LUA_OK (чтобы начать новую подпрограмму) или LUA_YIELD (возобновить сопрограмму).

lua_stringtonumber

[-0, +1, -]

size_t lua_stringtonumber (lua_State *L, const char *s);

Преобразование завершается нулем строку sв число, выталкивает это число в стек, и возвращает общий размер строки, то есть его длина плюс один. Преобразование может привести к целому или поплавка, в соответствии с лексическими конвенций Lua (см п.3.1 ). Строка может иметь начальные и конечные пробелы и знак. Если строка не является допустимым номером, возвращает 0 и не толкает ничего. (Обратите внимание , что результат может быть использован как логическое значение, правда , если преобразование завершается успешно.)

lua_toboolean

[-0, +0, -]

int lua_toboolean (lua_State *L, int index);

Преобразует значение Lua по заданному индексу до значения C булевой (0 или 1). Как и все тесты в Lua, lua_tobooleanвозвращает истину для любого значения Lua отличного от ложного и ноль ; в противном случае она возвращает ложь. (Если вы хотите , чтобы принимать только действительные логические значения, используйте lua_isbooleanдля проверки типа значения.)

lua_tocfunction

[-0, +0, -]

lua_CFunction lua_tocfunction (lua_State *L, int index);

Преобразует значение по данному индексу в функцию C. Это значение должно быть функцией C; в противном случае возвращает NULL.

lua_tointeger

[-0, +0, -]

lua_Integer lua_tointeger (lua_State *L, int index);

Эквивалент lua_tointegerxс isnumравным NULL.

lua_tointegerx

[-0, +0, -]

lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);

Преобразует значение Lua по заданному индексу подписанному интегрального типа lua_Integer. Значение Lua должно быть целым числом, или числом или строкой , конвертируемой в целое число (см §3.4.3 ); в противном случае lua_tointegerxвозвращает 0.

Если isnumнет NULL, его референтом присваивается логическое значение, указывающее , удалось ли операция.

lua_tolstring

[-0, +0, m ]

const char *lua_tolstring (lua_State *L, int index, size_t *len);

Преобразует значение Lua по заданному индексу в строку C. Если lenнет NULL, он устанавливает *len с длиной строки. Значение Lua должно быть строкой или числом; в противном случае функция возвращает NULL. Если значение является числом, то lua_tolstring также изменяет фактическое значение в стеке на строку . (Это изменение сбивает с толку , lua_next когда lua_tolstringприменяется к клавишам во время обхода таблицы.)

lua_tolstring возвращает указатель на строку состояния внутри Lua. Эта строка всегда имеет нулевое значение ( ' \0') после его последнего символа (как в C), но может содержать и другие нули в своем теле.

Поскольку Луа имеет сбора мусора, нет никакой гарантии , что указатель , возвращаемый lua_tolstring будет действовать после того, каксоответствующее значение Луа удаляется из стека.

lua_tonumber

[-0, +0, -]

lua_Number lua_tonumber (lua_State *L, int index);

Эквивалент lua_tonumberxс isnumравным NULL.

lua_tonumberx

[-0, +0, -]

lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);

Преобразует значение Lua по заданному индексу к типу C lua_Number(см lua_Number). Значение Lua должно быть числом или строкой ,конвертируемой в число (см §3.4.3 ); в противном случае lua_tonumberxвозвращает 0.

Если isnumнет NULL, его референтом присваивается логическое значение, указывающее , удалось ли операция.

lua_topointer

[-0, +0, -]

const char *lua_tostring (lua_State *L, int index);

Преобразует значение по данному индексу в обобщенный указатель C ( void*). Значение может быть UserData, таблица, нить, или функция; в противном случае, lua_topointerвозвращается NULL. Различные объекты дадут различные указатели. Там нет никакого способа , чтобы преобразовать указатель обратно к исходному значению.

Обычно эта функция используется только для хеширования и отладочной информации.

lua_tostring

[-0, +0, m ]

const char *lua_tostring (lua_State *L, int index);

Эквивалент lua_tolstringс lenравным NULL.

lua_tothread

[-0, +0, -]

lua_State *lua_tothread (lua_State *L, int index);

Преобразует значение по данному индексу в теме Lua (представлен как lua_State*). Это значение должно быть нить; в противном случае функция возвращает NULL.

lua_touserdata

[-0, +0, -]

void *lua_touserdata (lua_State *L, int index);

Если значение по данному индексу является полный UserData, возвращает свой адрес блока. Если значение является легким UserData, возвращает указатель. В противном случае, возвращается NULL.

lua_type

[-0, +0, -]

int lua_type (lua_State *L, int index);

Возвращает тип значения в данном допустимый индекс, или LUA_TNONEдля недействительный (но приемлемый) индекс. Типы возвращаемыхlua_typeзакодированы следующими константами , определенными в lua.h: LUA_TNIL(0), LUA_TNUMBER, LUA_TBOOLEAN, LUA_TSTRING, LUA_TTABLE,LUA_TFUNCTION, LUA_TUSERDATA, LUA_TTHREAD, и LUA_TLIGHTUSERDATA.

lua_typename

[-0, +0, -]

const char *lua_typename (lua_State *L, int tp);

Возвращает имя типа , кодируемого значением tp, которое должно быть одним значения , возвращенное lua_type.

lua_Unsigned

typedef ... lua_Unsigned;

Неподписанных версия lua_Integer.

lua_upvalueindex

[-0, +0, -]

int lua_upvalueindex (int i);

Возвращает псевдо-индекс, представляющий i-ю повышать стоимость функции хода (см §4.4 ).

lua_version

[-0, +0, v]

const lua_Number *lua_version (lua_State *L);

Возвращает адрес номер версии (статическая переменная C) хранится в ядре Lua. При вызове с действительным lua_State, возвращает адрес версии , используемой для создания этого состояния. При вызове NULL, возвращает адрес версии выполняется вызов.

lua_Writer

typedef int (*lua_Writer) (lua_State *L,
                           const void* p,
                           size_t sz,
                           void* ud);

Тип функции используемого устройства записи путем lua_dump. Каждый раз , когда он производит еще один кусок кусок, lua_dumpвызывает писатель, передавая буфер для записи ( p), его размер ( sz), а dataпараметр подается lua_dump.

Автор возвращает код ошибки: 0 означает отсутствие ошибок; любое другое значение означает ошибку и останавливает lua_dumpот повторного вызова писателя.

lua_xmove

[- ?, + ?, -]

void lua_xmove (lua_State *from, lua_State *to, int n);

Значения обмена между разными потоками одного и того же состояния.

Эта функция появляется nзначения из стека from, и помещает их в стек to.

lua_yield

[- ?, + ?, e ]

int lua_yield (lua_State *L, int nresults);

Эта функция эквивалентна lua_yieldk, но она не имеет продолжения (см §4.7 ). Поэтому, когда поток возобновляется, он продолжает функцию ,которая называется функцией призвание lua_yield.

lua_yieldk

[- ?, + ?, e ]

int lua_yieldk (lua_State *L,
                int nresults,
                lua_KContext ctx,
                lua_KFunction k);

Урожайность сопрограмму (Thread).

Когда вызывает функцию C lua_yieldk, бегущая сопрограммная приостанавливает его исполнение, и призыв к lua_resume который начал этот сопрограмм возвращается. Параметр nresultsпредставляет число значений из стека , который будет передан в результатах lua_resume.

Когда сопрограммная возобновляется снова, Lua вызывает данную функцию продолжения , kчтобы продолжить выполнение функции C , которые получают (см §4.7 ). Эта функция продолжения получает тот же стек от предыдущей функции, причем nудалены и заменены аргументам ,передаваемым результаты lua_resume. Кроме того, функция продолжения принимает значение , ctx  которое было передано lua_yieldk.

Как правило, эта функция не возвращает; когда в конечном итоге сопрограммная возобновляется, он продолжает выполнение функции продолжения. Тем не менее, есть один особый случай, который , когда эта функция вызывается из внутренней линии или счета крюка (см §4.9 ). В этом случае, lua_yieldk следует назвать, без продолжения (вероятно , в форме lua_yield) и без каких - либо результатов, и крючок должен вернуться сразу после звонка. Lua будет давать и, когда сопрограммная возобновляется, он продолжит нормальное выполнение функции (Lua), инициировавшего крюк.

Эта функция может вызвать ошибку, если она вызывается из потока с помощью отложенного вызова C без функции продолжения, или он вызывается из потока, который не работает внутри резюме (например, основной поток).

4.9 - отладочная интерфейс

Не Lua имеет никаких встроенных средств отладки. Вместо этого он предлагает специальный интерфейс с помощью функций и крючков . Этот интерфейс позволяет создавать различные виды отладчиков, профайлеров и другие инструменты , которые нуждаются в "внутренней информации" от интерпретатора.

lua_Debug

typedef struct lua_Debug {
  int event;
  const char *name;           /* (n) */
  const char *namewhat;       /* (n) */
  const char *what;           /* (S) */
  const char *source;         /* (S) */
  int currentline;            /* (l) */
  int linedefined;            /* (S) */
  int lastlinedefined;        /* (S) */
  unsigned char nups;         /* (u) number of upvalues */
  unsigned char nparams;      /* (u) number of parameters */
  char isvararg;              /* (u) */
  char istailcall;            /* (t) */
  char short_src[LUA_IDSIZE]; /* (S) */
  /* private part */
  other fields
} lua_Debug;

Структура используется для выполнения различных частей информации о функции или записи активации. lua_getstackЗ аполняет только приватной части этой структуры, для последующего использования. Для заполнения других полей lua_Debugс полезной информацией, звоните lua_getinfo.

Поля lua_Debug имеют следующие значения:

  • source: Имя фрагмента , который создал функцию. Если sourceначинается с ' @', это означает , что функция была определена в файле , где имя файла следует за ' @'. Если sourceначинается с ' =', остальная часть его содержания описания источника в пользовательском-зависимым образом. В противном случае функция была определена в строке , где sourceнаходится эта строка.
  • short_src: А " для печати" вариант source, который будет использоваться в сообщениях об ошибках.
  • linedefined: Номер строки , где начинается определение функции.
  • lastlinedefined: Номер строки , где заканчивается определение функции.
  • what: Строка , "Lua" если функция является функцией Lua, "C" если она является функцией C, "main" если основная часть куска.
  • currentline: Текущая строка , где данная функция выполняется. Если никакой информации линии отсутствует, currentline устанавливается в -1.
  • name: Разумное название для данной функции. Так как функции в Lua являются значения первого класса, они не имеют фиксированное имя: некоторые функции могут быть значением нескольких глобальных переменных, в то время как другие могут быть сохранены только в поле таблицы. lua_getinfo Функция проверяет , как функция была вызвана , чтобы найти подходящее имя. Если он не может найти имя, а затем name устанавли вается в NULL.
  • namewhat: Объясняет name поле. Значение  namewhat может быть "global", "local", "method", "field", "upvalue", или ""(пустая строка), всоответствии с тем, как была вызвана функция. (Lua использует пустую строку , когда нет другого выбора , кажется, относится.)
  • istailcall: Верно , если эта функция вызова была вызвана хвостового вызова. В этом случае абонент этого уровня не в стеке.
  • nups: Количество upvalues функции.
  • nparams: Количество фиксированных параметров функции (всегда равно 0 для функций C).
  • isvararg: Верно , если функция является функцией vararg (всегда верно для функций C).

lua_gethook

[-0, +0, -]

lua_Hook lua_gethook (lua_State *L);

Возвращает текущую функцию крюка.

lua_gethookcount

[-0, +0, -]

int lua_gethookcount (lua_State *L);

Возвращает текущее количество крючков.

lua_gethookmask

[-0, +0, -]

int lua_gethookmask (lua_State *L);

Возвращает текущую маску крюк.

lua_getinfo

[- (0 | 1), + (0 | 1 | 2), е ]

int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);

Получает информацию о конкретной функции или вызова функции.

Для того, чтобы получить информацию о вызове функции, параметр arдолжен быть действительным запись активации , которая была заполнена предыдущим вызовом lua_getstackили дали в качестве аргумента к крюку (см lua_Hook).

Чтобы получить информацию о функции вы толкаете его в стек и запустить whatстроку с символом ' >'. (В этом случае lua_getinfoпоявляется функция от вершины стека). Например, чтобы знать , в какой строке функция fбыла определена, вы можете написать следующий код:

     lua_Debug ar;
     lua_getglobal(L, "f");  /* get global 'f' */
     lua_getinfo(L, ">S", &ar);
     printf("%d\n", ar.linedefined);

Каждый символ в строке what выбирает некоторые поля структуры arдолжны быть заполнены или значение , которое должно быть в стек:

  • ' n': Заполняет поле nameи namewhat;
  • ' S': Заполняет поля source, short_src, linedefined, lastlinedefined, и what;
  • ' l': Заполняет поле currentline;
  • ' t': Заполняет поле istailcall;
  • ' u': Заполняет поля nups, nparamsи isvararg;
  • ' f': Помещает в стек функцию , которая работает на данном уровне;
  • ' L': Проталкивает в стек таблицы, индексы которых число строк, которые действуют на функции. (А действует линия представляет собой линию с некоторой связанной кодом, то есть строка , где вы можете поставить точку останова. Недопустимого линии включают в себя пустые строки и комментарии.)Если эта опция задана вместе с опцией ' f', его таблица выталкивается после функции.

Эта функция возвращает 0 в случае ошибки (например, неверный вариант в what).

lua_getlocal

[= 0, + (0 | 1), -]

const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);

Получает информацию о локальной переменной данной записи активации или данной функции.

В первом случае параметр arдолжен быть корректным запись активации , который был заполнен предыдущим вызовом lua_getstackили заданный в качестве аргумента к крюку (см lua_Hook). Индекс nвыбирает , какой из локальной переменной для проверки; см debug.getlocalПодробную информацию о переменных индексов и названий.

lua_getlocal выталкивает значение переменной в стек и возвращает его имя.

Во втором случае, arдолжен быть NULLи функция для инспекции должна быть в верхней части стека. В этом случае только параметры функций Lua открыты (как нет никакой информации о том, какие переменные являются активными) и значения не помещаются в стек.

Возвращает NULL(и не толкает ничего) , когда индекс больше , чем число активных локальных переменных.

lua_getstack

[-0, +0, -]

int lua_getstack (lua_State *L, int level, lua_Debug *ar);

Получает информацию о стеке интерпретатора во время выполнения.

Эта функция заполняет частей lua_Debugструктуры с идентификацией записи активации функции исполняющего на заданном уровне. Уровень 0 текущая функция работает, в то время как определять разность высот п + 1 является функцией , которая имеет называемый уровень п (для хвостовых вызовов, которые не рассчитывают на стеке , кроме). Когда нет никаких ошибок, lua_getstackвозвращает 1; при вызове с уровнем больше , чем глубина стека, она возвращает 0.

lua_getupvalue

[= 0, + (0 | 1), -]

const char *lua_getupvalue (lua_State *L, int funcindex, int n);

Получает информацию о n-м повышать стоимость закрытия в индексе funcindex. Это толкает ценность в повышать стоимость в стек и возвращает его имя. Возвращает NULL(и не толкает ничего) , когда индекс nбольше , чем число upvalues.

Для функций C, эта функция использует пустую строку в "" качестве имени для всех upvalues. (Для функций Lua, upvalues являются внешние локальные переменные , которые функция использует, и что, следовательно , включаются в его закрытия.)

Upvalues не имеют особого порядка, так как они активны по всей функции. Они пронумерованы в произвольном порядке.

lua_Hook

typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);

Введите для функций отладки крюк.

Всякий раз , когда крючок называется, его arаргумент его поле eventустанавливается на конкретное событие , которое инициировало крюк. Lua идентифицирует эти события со следующими константами: LUA_HOOKCALL, LUA_HOOKRET, LUA_HOOKTAILCALL, LUA_HOOKLINEи LUA_HOOKCOUNT. Кроме того, для ряда событий, поле currentlineтакже устанавливается. Для того, чтобы получить значение любого другого поля ar, крючок должен позвонить lua_getinfo.

Для событий вызова, eventможет быть LUA_HOOKCALL, нормальное значение, или LUA_HOOKTAILCALL, за хвост вызова; в этом случае, не будет никакого соответствующего возврата событие.

В то время как Lua работает крючок, он отключает другие вызовы на крючках. Поэтому, если крюк выполняет обратный вызов Lua, чтобы выполнить функцию или кусок, это исполнение происходит без каких-либо звонков на крючках.

Функции Крюк не может иметь продолжений, то есть, они не могут назвать lua_yieldk, lua_pcallkили lua_callkс ненулевым k.

Функции Крюк может дать при следующих условиях: Только подсчет и линейные события могут дать; с выходом, функция крючок должен завершить ее выполнение вызова lua_yieldс nresultsравным нулю (то есть, без каких - либо значений).

lua_sethook

[-0, +0, -]

void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);

Устанавливает функцию отладки крюк.

Аргумент fявляется функцией крючка. maskУказывает на какие события крючок будет называться: она формируется побитового OR константLUA_MASKCALL, LUA_MASKRET, LUA_MASKLINEи LUA_MASKCOUNT. countАргумент имеет смысл только , когда маска включает в себя LUA_MASKCOUNT. Для каждого события, крючок называется , как описано ниже:

  • Крючок вызов: вызывается , когда интерпретатор вызывает функцию. Крюк вызывается только после того, как Lua входит в новую функцию, до того , как функция получает свои аргументы.
  • Обратный крюк: вызывается , когда интерпретатор возвращается из функции. Крюк вызывается непосредственно перед Lua покидает функцию. Там нет стандартного способа получить доступ к значениям, возвращаемых функцией.
  • Линия крюк: вызывается , когда интерпретатор собирается начать выполнение новой строки кода, или когда он отскакивает назад в коде (даже в той же строке). (Это событие происходит только тогда , когда Lua выполняет функцию Lua.)
  • Отсчет крюк: вызывается после того, как интерпретатор выполняет каждые countинструкции. (Это событие происходит только тогда , когда Lua выполняет функцию Lua.)

Крючок отключена путем установки maskна ноль.

lua_setlocal

[- (0 | 1), +0, -]

const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);

Устанавливает значение локальной переменной данной записи активации. Он присваивает значение в верхней части стека в переменную и возвращает его имя. Он также извлекает значение из стека.

Возвращает NULL(и УОЗ ничего) , когда индекс больше , чем число активных локальных переменных.

Параметры arи nявляются , как и в функции lua_getlocal.

lua_setupvalue

[- (0 | 1), +0, -]

const char *lua_setupvalue (lua_State *L, int funcindex, int n);

Устанавливает значение повышать стоимость действия замыкания. Он присваивает значение в верхней части стека до и возвращает повышать стоимость его имя. Он также извлекает значение из стека.

Возвращает NULL(и УОЗ ничего) , когда индекс nбольше , чем числа upvalues.

Параметры funcindexи nявляются , как и в функции lua_getupvalue.

lua_upvalueid

[-0, +0, -]

void *lua_upvalueid (lua_State *L, int funcindex, int n);

Возвращает уникальный идентификатор для повышать стоимость пронумерованных n от закрытия в индексе funcindex.

Эти уникальные идентификаторы позволяют программе проверить, могут ли различные замыканиями акций upvalues. Lua затворы, которые разделяют (повышать стоимость, то есть, что получить доступ к той же внешней локальной переменной) будет возвращать одинаковые идентификаторы для этих индексов повышать стоимость.

Параметры funcindexи nявляются , как и в функции lua_getupvalue, но nне может быть больше , чем количество upvalues.

lua_upvaluejoin

[-0, +0, -]

void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
                                    int funcindex2, int n2);

Сделать n1-я повышать стоимость закрытия Lua по индексу funcindex1 относятся к n2-му повышать стоимость закрытия Lua по индексуfuncindex2.

Дале --->

Translate »