tsv

NAME

tsv — Часть расширения Tcl для потоков, позволяющая на уровне скрипта манипулировать данными, общими для нескольких потоков.

SYNOPSIS

DESCRIPTION

ELEMENT COMMANDS

tsv::names ?pattern?

tsv::object varname element

tsv::set varname element ?value?

tsv::get varname element ?namedvar?

tsv::unset varname ?element?

tsv::exists varname element

tsv::pop varname element

tsv::move varname oldname newname

tsv::incr varname element ?count?

tsv::append varname element value ?value . . .?

tsv::lock varname arg ?arg . . .?

tsv::handlers

Имя

Синтаксис

Описание

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

Команды элементов

tsv::names ?pattern?

Возвращает имена общих переменных, соответствующих необязательному ?pattern?, или все известные переменные, если pattern опущен.

tsv::object varname element

Создает команду доступа к объекту для element в общей переменной varname. Используя эту команду, можно применить большинство других команд для общих переменных как методы команд объекта элемента. Команда объекта автоматически удаляется, когда элемент, на который она указывает, удаляется.

% tsv::set foo bar "A shared string"
    % set string [tsv::object foo bar]
    % $string append " appended"
    => A shared string appended

tsv::set varname element ?value?

Устанавливает значение element в общей переменной varname в value и возвращает значение вызывающей стороне. value можно опустить, в этом случае команда вернет текущее значение элемента. Если элемент не найден, генерируется ошибка.

tsv::get varname element ?namedvar?

Извлекает значение element из общей переменной varname. Если необязательный аргумент namedvar задан, значение сохраняется в именованной переменной. Возвращаемое значение команды зависит от наличия необязательного аргумента namedvar. Если аргумент опущен, и запрашиваемый элемент не найден в общем массиве, команда генерирует ошибку. Если же необязательный аргумент указан, команда возвращает true (1), если элемент найден, или false (0), если элемент не найден.

tsv::unset varname ?element?

Удаляет element из общей переменной varname. Если необязательный элемент не задан, удаляет всю переменную.

tsv::exists varname element

Проверяет, существует ли element в общей переменной varname, и возвращает true (1), если существует, или false (0), если нет.

tsv::pop varname element

Возвращает значение element в общей переменной varname и удаляет элемент в одном атомарном действии.

tsv::move varname oldname newname

Переименовывает элемент oldname в newname в общей переменной varname. Это фактически выполняет последовательность операций get/unset/set, но все в одном атомарном шаге.

tsv::incr varname element ?count?

Аналогично стандартной команде Tcl incr, но инкрементирует значение element в общей переменной varname вместо переменной Tcl.

tsv::append varname element value ?value . . .?

Аналогично стандартной команде Tcl append, но добавляет одно или несколько значений к element в общей переменной varname вместо переменной Tcl.

tsv::lock varname arg ?arg . . .?

Эта команда конкатенирует переданные аргументы и вычисляет полученный скрипт под защитой внутреннего мьютекса. Во время вычисления скрипта вся общая переменная блокируется. Для команд общих переменных внутри скрипта внутренняя блокировка отключена, поэтому не может произойти тупик. Также разрешено удалить общую переменную изнутри скрипта. Общая переменная автоматически создается, если она не существовала во время первой операции lock.

% tsv::lock foo {
        tsv::lappend foo bar 1
        tsv::lappend foo bar 2
        puts stderr [tsv::set foo bar]
        tsv::unset foo
    }

tsv::handlers

Возвращает имена всех постоянных обработчиков хранения, включенных во время компиляции. Подробности см. в разделе ARRAY COMMANDS.

Команды списков

tsv::lappend varname element value ?value . . .?

Похожа на стандартную команду Tcl lappend, но добавляет одно или несколько значений к элементу element в общей переменной varname, а не в переменную Tcl.

tsv::linsert varname element index value ?value . . .?

Похожа на стандартную команду Tcl linsert, но вставляет одно или несколько значений в позицию списка index в элементе element общей переменной varname вместо переменной Tcl.

tsv::lreplace varname element first last ?value . . .?

Похожа на стандартную команду Tcl lreplace, но заменяет одно или несколько значений между позициями first и last в элементе element общей переменной varname вместо переменной Tcl.

tsv::llength varname element

Похожа на стандартную команду Tcl llength, но возвращает длину элемента element в общей переменной varname вместо переменной Tcl.

tsv::lindex varname element ?index?

Похожа на стандартную команду Tcl lindex, но возвращает значение в позиции списка index элемента element из общей переменной varname вместо переменной Tcl.

tsv::lrange varname element from to

Похожа на стандартную команду Tcl lrange, но возвращает значения между позициями from и to в элементе element общей переменной varname вместо переменной Tcl.

tsv::lsearch varname element ?options? pattern

Похожа на стандартную команду Tcl lsearch, но ищет элемент element в общей переменной varname вместо переменной Tcl.

tsv::lset varname element index ?index . . .? value

Похожа на стандартную команду Tcl lset, но устанавливает элемент element в общей переменной varname вместо переменной Tcl.

tsv::lpop varname element ?index?

Похожа на стандартную команду Tcl lindex, но помимо возврата также вырезает значение из элемента element из общей переменной varname в одной атомарной операции. В отличие от команды Tcl lindex, эта команда не возвращает значение вызывающей стороне.

tsv::lpush varname element ?index?

Эта команда выполняет обратное действие команды tsv::lpop. Как и её аналог, она не возвращает значение вызывающей стороне.

Команды массивов

tsv::array set varname list

Делает то же, что и стандартная команда Tcl array set.

tsv::array get varname ?pattern?

Делает то же, что и стандартная команда Tcl array get.

tsv::array names varname ?pattern?

Делает то же, что и стандартная команда Tcl array names.

tsv::array size varname

Делает то же, что и стандартная команда Tcl array size.

tsv::array reset varname list

Делает то же, что и стандартная команда Tcl array set, но очищает varname и устанавливает новые значения из списка атомарно.

tsv::array bind varname handle

Привязывает varname к постоянному хранилищу handle. Формат handle — <handler>:<address>, где <handler> — "gdbm" для GNU Gdbm и "lmdb" для LMDB, а <address> — путь к файлу базы данных.

tsv::array unbind varname

Отвязывает общий массив от привязанного постоянного хранилища.

tsv::array isbound varname

Возвращает true (1), если общий varname привязан к постоянному хранилищу, или ноль (0), если нет.

Команды списков с ключами

Список с ключами — это список, в котором каждый элемент содержит пару ключ-значение. Эти пары элементов хранятся как списки, где ключ — первый элемент списка, а значение — второй. Пары ключ-значение называются полями. Вот пример списка с ключами:

{{NAME  {Frank  Zappa}} {JOB {musician and composer}}}

{ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}

tsv::keyldel varname keylist key

Удаляет поле, указанное ключом key, из списка с ключами keylist в общей переменной varname. Это удаляет и ключ, и значение из списка с ключами.

tsv::keylget varname keylist key ?retvar?

Возвращает значение, связанное с ключом key, из списка с ключами keylist в общей переменной varname. Если необязательный retvar не указан, значение возвращается как результат команды. В этом случае, если ключ не найден в списке, произойдёт ошибка.

Если retvar указан и key находится в списке, значение возвращается в переменную retvar, а команда возвращает 1, если ключ был присутствовал в списке. Если key нет в списке, команда возвращает 0, а retvar остаётся неизменным. Если для retvar указано {}, значение не возвращается, что позволяет программисту Tcl определить, присутствует ли key в списке с ключами, не устанавливая переменную как побочный эффект.

tsv::keylkeys varname keylist ?key?

Возвращает список ключей в списке с ключами keylist в общей переменной varname. Если указан key, это имя поля ключа, подполя ключей которого необходимо получить.

tsv::keylset varname keylist key value ?key value . .?

Устанавливает значение, связанное с ключом key, в списке с ключами keylist, в значение value. Если keylist не существует, он создаётся. Если key в данный момент не находится в списке, он будет добавлен. Если он уже существует, value заменяет существующее значение. При необходимости можно указать несколько ключевых слов и значений.

Обсуждение

К сожалению, из-за внутренней структуры ядра Tcl нет возможности для полной интеграции переменных с общим доступом в синтаксис Tcl. Весь доступ к общим данным должен осуществляться с помощью предоставленных команд пакета. Также не поддерживаются отслеживания переменных. Но даже так, преимущества лёгкого, простого и безопасного управления общими данными перевешивают наложенные ограничения.

Авторы

См. также