Агенты

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

Чтобы агент выполнился в заданное время, его необходимо зарегистрировать в системе при помощи метода CAgent::AddAgent. Удалить регистрацию можно с помощью функции CAgent::RemoveAgent.

Если функция-агент принадлежит модулю, то перед ее выполнением этот модуль будет автоматически подключаться, а именно будет подключаться файл /bitrix/modules/ID модуля/include.php. В этом случае необходимо убедиться, что функция будет доступна после подключения этого файла.

Если функция не принадлежит ни одному из модулей, то ее необходимо разместить в файле /bitrix/php_interface/init.php. Этот файл автоматически подключается в прологе.

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

Список используемых в системе агентов приводится на странице Список агентов (Настройки > Настройки продукта > Агенты).

Периодические и непериодические

Исторически агенты называются "периодические" и "непериодические", хотя правильнее было бы сказать: "повторяющиеся" и "неповторяющиеся". Сложившиеся названия решили не менять.

Так же решили не менять и интерфейс настройки агента в административном разделе сайта:

Тип агента зависит от программиста, который написал код агента. Программист может сделать агента, который повторится бесконечное число раз. Или только 2-3 раза в зависимости от условий. Пример функций агентов повторяющихся бесконечное число раз:

// пример функций агентов

function TestAgentPeriod()
{
	AddMessage2Log( "Периодический BX_CRONTAB:".BX_CRONTAB." BX_CRONTAB_SUPPORT:".BX_CRONTAB_SUPPORT );   
	return "TestAgentPeriod();";
}


function TestAgentNotPeriod()
{
	AddMessage2Log( "Непериодический BX_CRONTAB:".BX_CRONTAB." BX_CRONTAB_SUPPORT:".BX_CRONTAB_SUPPORT );
	return "TestAgentNotPeriod();";
}

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

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

  Старое назначенное время агента + интервал

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

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

  Время завершения последнего запуска агента (выполнение return) + интервал

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

  Абсолютное большинство агентов непериодические.

Ограничения

При использовании технологии учтите, что:

• Переменная USER в агентах отсутствует. Точнее она может быть создана на сервере хостинга, но нет никакой гарантии, что это будет объект класса CUser.
  При необходимости рекомендуется создавать в агенте объект $USER, что-то с ним сделать и уничтожить.
• В агентах нельзя проводить авторизацию методом Authorize.
• Отсутствует константа SITE_ID, так как агент может выполниться и на странице административного раздела.
• На многоязычных сайтах нельзя заранее узнать какой будет язык.
• Агенты выполняются в однопоточном режиме с блокировкой на MySQL на 10 минут. Новый вызов агента возможен только после того, как отработает предыдущий вызов. Блокировка БД может потеряться если закроется соединение с ней. 10 минут ожидания это - дополнительная защита от повторного запуска, агентов которые не корректно отработали.