To check your current agent cycle time and number of agents use the Hypertext Status view (accessed from the View menu).
Controlling Agent Priority
The $AgentPriority attribute, 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.
When set to 'Off' (-1), Tinderbox 'freezes' the contents of an agent. This means that when turned off the agent retains whatever children it had at the last update cycle before it was turned off. Agents switched 'off' do not get updated voa the file menu's 'Update now' command. It is thus not possible to have an agent that is only 'manually' updated.
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 system attribute 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.
Altering Content of Disabled Agents
When switched off, an agent retains the aliases it had at that point. You can also do several things you can't do when the agent is active:
- Re-order the aliases - e.g. alter the outline order or map location
- Delete aliases (though you can't add new notes aliases)
Note that re-enabling the agent may undo some of the above order/location changes and may add back deleted aliases.
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 in succession to ensure all agents are fired - as those agents with lower priority settings are omitted from some firing cycles (i.e. update); the lower the priority setting, the more often an agent is omitted from the cycle. For instance, for the aTbRef TBX it can take 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 TBX isn't properly updated after being opened, some sections (agent containers) my be empty until enough update cycles has completed to populate even the lowest priority ones.
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.