Controlling Agent Update Cycle Time

To check your current agent cycle time and number of agents use the Hypertext Status dialog (accessed from the Views menu).

Controlling Agent Priority

The AgentPriority attribute, introduced in v2.5.0 allows the user to set the periodicity with which agents are run. This allows agents tracking low rate of change queries to be run less often, reducing the agent cycle time. Queries are not run for those agents that are turned off altogether. Again, this reduces the overall cycle time.

The feature was improved in v3.5.0 by making TB 'freeze' the contents of an agent when set to 'Off' (-1). This means that when turned off the agent retains whatever children it had at the last update cycle before it was turned off.

Thus agents can be used to harvest sets of aliases and then turned off to 'fix' the content. Alternatively, such agents' priority can be turned on/up to update content before an export and then turned off/down. aTbRef uses this method for agents used to do tasks such as representing the main attribute list in alternate forms such as by data type or TBX group.

To avoid having to change each agent by hand, they are located by an 'utility' agent '@attributes_agents_frequency' with this query:

#inside(Attribute Data Types)|#inside(Attribute Groups)

An action sets priority for the matches found (which here will be agents):

AgentPriority=10

Note the AgentPriority must be set a number. Using 'Low' instead of '10' results - due to type coercion - in a value of 'Highest' and not quite what's wanted.

In turn, this utility agent is turned off when not in use. When enabled, it allows 18 agents to be controlled via one setting.

Although the Hypertext Status dialog will tell you how many agents you have, you may be you're not sure where they are in your TBX. An agent can help using this query:

AgentQuery!=

Notes, adornments, etc., won't have an AgentPriority value.

Now you have all the agents you can use use the Show Original command to locate the agent. To aid more granular control of separate groups of agents, consider their location in the TBX. For example, in aTbRef the exported content, with the exception of the RSS feeds is all in one note hierarchy. A separate root-level note 'UTILS' contains, sets of prototypes and utility agents. Meanwhile both the Attribute and Export Code section use agents to present their lists in different splits; because the agents are within a containing (note) the #inside() query syntax can be used to easily locate them.

If your agents are more scattered in the TBX consider using a user set/attribute to flag agents so an agent may easily find them. however location based queries (as above) are more efficient, for reason discussed further below.

Making Agents More Efficient

In small TBXs you won't notice your agent settings affecting update time but as a TBX grows in size and complexity, ideally your agents should target as few notes as possible - or at least where that is possible to do so - in order to keep performance snappy. In this context, think about using # inside() and #descendedFrom() as part of your queries. The former allows you target the immediate children of a given note and the latter any descendant of a given note.

For example, if searching for text in children of a note called 'The Library', it is much faster to run:

#inside(The Library) & Text(When.+April)

... than ...

Text(When.+April) & #inside(The Library)

... because the # inside() part of the query cuts the number of notes searched. The second example does a regular expression search against all notes in the TBX before the results are then filtered to only children of 'The Library).

It is much faster, in performance terms to factor out very complex queries into separate agents, and then use #inside to leverage those agents, than to repeat the queries. Complex regular expressions are also comparatively heavy users of TB thinking time so consider if there's not an easier way to find the same match. If using such an expression to, for example, find misspellings, you might delete the agent when done or at least turn it off between major editing sessions.

Check That Results Make Sense

Finally, beware of broken agents. Sometimes, a syntax error can create an agent that finds nothing (or the wrong things), but takes an age to do so.

Use Global Controls for TBX

Trying to do text editing and getting disturbed by the hourglass? In a big TBX with many agents this can happen. In such circumstances it can help to disable the "Update Agents Automatically" option (via the File menu) - just don't forget to enable it again if your TBX relies on ongoing use of live agents.

If you either don't use (or have temporarily turned off) automatic updates, you can use the same (File) menu to force a one-off update via "Update now" (cmd+ctrl+=). However, if you use a lot of agents and have different priorities set it can be a wise idea to use this update call several times to ensure all agents are fired - as lower priority settings are dropping some agents out of firing every cycle (i.e. update). For instance, for this TBX normally needs 3 or 4 successive "Update now" calls to ensure all the low priority agents are run. Failure to do so means that sections like the listings of attributes by data type don't get populated - given that the HTML output expects each alias to be exported as a separate HTML file. If the YBX isn't properly updated, some sections my be empty.

However, Tinderbox is aware of the latter issue and when doing an HTML export, Tinderbox should update all agents regardless of priority before export (including agents set to 'Off') but it is still worth checking output to ensure that output depending on several agent's actions has actually been generated. Once happy the process is working as expected, you can ease back on such checks.

Put another way, when you get creative with agents and start to create more complex TBXs, don't just check for the obvious output but look for unintended consequences - either of your query/action/rule coding or simply the inheritances and agent activities you've put in place.

Licensed under Creative Commons Attribution-Noncommercial-Share Alike 3.0 License
[See aTbRef CC licence Attribution/Waiver info info]