Batch close

needs(better_code_samples);

Function Syntax

boolean batch_close()

After a batch_open(), certain functions that generate a server hit on each call are queued up, rather than executed immediately. When batch_close() is called, it will then execute all of them at once (hopefully with fewer server hits).

The functions that benefit from being batched include autosell(), mallsell(), and the various put_X(), take_X() functions that move items to or from the closet, storage, display, or stash. Most of the KoL interfaces for these are capable of transferring up to 11 items at once, but that can't otherwise be expressed in ASH. More details:

• Caution is required when using more than one batchable function in a single batch, since they won't be executed in the same order you wrote them.
  • What happens in this case is that all instances of the first encountered function are executed, then all instances of the second encountered function, and so on.
  • This should produce the expected results in cases such as a loop that pulls an item from storage, and then puts it in your closet.
    • Inside of a batch, all the pulls get processed at once, and then all the closet puts.
• put_X() and take_X() with the same source (the closet, for example) cannot be used in the same batch.
• Batches are accumulated on a per-script-invocation basis.
  • Having an open batch does not affect execution of any other script that's running at the same time.
  • Any commands batched by a script that was aborted are discarded - they won't mysteriously be executed by the next script that calls batch_close()

Any failure of batched commands can be captured and tested via the return value of batch_close(), just as you'd normally check the return value of the individual functions being batched. However, there's no way to tell just how much progress had been made before the failure, so it's unlikely that a script could meaningfully continue after that point.

(Note: this function description taken in its entirety, with only slight formatting changes, from jasonharper's log notes on r7552.)

Code Sample

This will remove all items from a characters closet. None of the items are removed until the batch is closed so that they can be removed in groups of 11 to minimize server hits.

batch_open();

// Check every item to see if there are any in the closet.
foreach doodad in $items[]
   if(closet_amount(doodad)>0)
      take_closet(closet_amount(doodad), doodad);

batch_close();

}

See Also

batch_open()