module: async
docs: |
  Provides commands for executing blocks asynchronously.
  
  Asynchronous blocks are executed in the same thread as regular commands, so it's recommended
  to avoid long running operations in these blocks. Exception to these are commands which require fetching
  data from the database.
symbols:
  - name: do
    syntax: async:do BLOCK
    docs: |
      Schedules a block to be executed at the conclusion of all other running commands.
      Blocks are place in a queue in the order the call to `async:do` is made, with a maximum
      queue size of 100 blocks. If the queue is full, the command will return an error.
    example: |
      async:do {
        echo "World"
      }
      echo "Hello"
  - name: in
    syntax: async:in SECONDS BLOCK
    docs: |
      Schedules a block to be executed in SECONDS seconds. Once the timout has ellapsed, the block will
      be placed on the queue and will be executed once all other pending blocks have been consumed.
    example: |
      async:in 5 {
        echo "5 seconds have ellapsed"
      }
  - name: query
    syntax: async:query EXPRESSION [QUERY_ARGS] BLOCK [OPTIONS]
    docs: |
      Executes the query in the background and schedules BLOCK once the resultset is available. The available
      options match that of rs:query.
      
      Note: the RC files are invoked before the table picker is shown, so any async:query calls invoked during
      startup should have the `-table` option set.
    example: |
      async:query 'pk = $arg' [arg:"abc123"] { |rs|
        echo $rs.First.pk
      }