Argobots Threading and Tasking Framework

To install Argobots, follow these steps in order. Ensure you have a C compiler (like gcc) installed. You should also identify your shell (e.g., bash, csh, or tcsh) using echo $SHELL to use the correct command syntax for redirection.

1. Preparation

If using a release tarball:

tar xzf argobots.tar.gz
cd argobots

Note: If your tar does not support the -z option, use:

gunzip argobots.tar.gz
tar xf argobots.tar
cd argobots

If using a GitHub clone:

cd argobots
./autogen.sh

2. Configure

Choose a non-existent or empty installation directory. Use the --prefix flag to specify it.

For bash/standard shells:

./configure --prefix=/home/USERNAME/argobots-install 2>&1 | tee c.txt

For csh or tcsh:

./configure --prefix=/home/USERNAME/argobots-install |& tee c.txt

3. Build

make 2>&1 | tee m.txt

For csh or tcsh:

make |& tee m.txt

If the build fails, try cleaning and running with verbose output:

make clean
make V=1 2>&1 | tee m.txt

4. Install

This step copies the required files into the bin subdirectory of your chosen prefix.

For bash/standard shells:

make install 2>&1 | tee mi.txt

For csh or tcsh:

make install |& tee mi.txt

If you encounter issues, follow these steps:

1. Check the FAQ: Visit the Argobots Wiki FAQ.
2. Search Mailing Lists: Check the discuss@argobots.org archive.
3. Email the Developers: If the above fail, email discuss@argobots.org. You must subscribe to the list first. Important: When emailing, compress and attach the following files generated during your build process:
   • argobots/c.txt (from configure)
   • argobots/m.txt (from make)
   • argobots/mi.txt (from make install)
   • argobots/config.log (from configure) Include the specific error message and a minimal reproduction case if possible.
4. GitHub Issues: For confirmed bugs, report them at github.com/pmodels/argobots/issues. It is recommended to email the mailing list first.

To enable logging and debug messages, Argobots must be configured with the --enable-debug flag. The behavior of these variables depends on how --enable-debug was set:

• ABT_USE_LOG (or ABT_ENV_USE_LOG): Enables logging.
  • Values: 1, Y, 0, N
  • Default: 1 if configured with --enable-debug=log or --enable-debug=all; 0 if configured with --enable-debug=most
• ABT_USE_DEBUG (or ABT_ENV_USE_DEBUG): Enables debug messages.
  • Values: 1, Y, 0, N
  • Default: 1 if configured with --enable-debug=log or --enable-debug=all; 0 if configured with --enable-debug=most
• ABT_USE_EVENT_DEBUG (or ABT_ENV_USE_EVENT_DEBUG): Enables debug messages for events. This is effective when configured with --enable-power-event or --enable-publish-info.
  • Values: 1, Y, 0, N
  • Default: 1 if configured with --enable-debug=log or --enable-debug=all; 0 if configured with --enable-debug=most
• ABT_PRINT_CONFIG (or ABT_ENV_PRINT_CONFIG): Determines if the configuration is printed during ABT_init().
  • Values: 1, Y, 0, N
  • Default: 0

Control memory allocation, page sizes, and cache alignment:

• ABT_CACHE_LINE_SIZE (or ABT_ENV_CACHE_LINE_SIZE): Cache line size. (Unsigned integer, Default: 64)
• ABT_OS_PAGE_SIZE (or ABT_ENV_OS_PAGE_SIZE): OS page size. (Unsigned integer, Default: 4096)
• ABT_HUGE_PAGE_SIZE (or ABT_ENV_HUGE_PAGE_SIZE): Huge page size. (Unsigned integer, Default: 2097152)
• ABT_MEM_PAGE_SIZE (or ABT_ENV_MEM_PAGE_SIZE): Page size for memory allocation. (Unsigned integer, Default: 2097152)
• ABT_MEM_STACK_PAGE_SIZE (or ABT_ENV_MEM_STACK_PAGE_SIZE): Stack page size for memory allocation. (size_t, Default: 8388608)
• ABT_MEM_MAX_NUM_STACKS (or ABT_ENV_MEM_MAX_NUM_STACKS): Max stacks each ES can keep during execution. (Unsigned integer, Default: 65536)
• ABT_MEM_LP_ALLOC (or ABT_ENV_MEM_LP_ALLOC): Method for allocating large pages.
  • Values: malloc, mmap_rp, mmap_hp_rp, mmap_hp_thp, thp
  • Default: mmap_hp_rp if anonymous page is supported, otherwise malloc

Adjust the runtime behavior of execution streams and the scheduler using these variables:

• ABT_MAX_NUM_XSTREAMS (or ABT_ENV_MAX_NUM_XSTREAMS): Maximum number of ESs that can be created. (Unsigned integer, Default: # of hardware threads)
• ABT_KEY_TABLE_SIZE (or ABT_ENV_KEY_TABLE_SIZE): Default number of key table entries. (Unsigned integer, Default: 4)
• ABT_THREAD_STACKSIZE (or ABT_ENV_THREAD_STACKSIZE): Default stack size for User-Level Threads (ULT). (size_t, Default: 16384)
• ABT_SCHED_STACKSIZE (or ABT_ENV_SCHED_STACKSIZE): Default stack size for the scheduler. (size_t, Default: 4194394)
• ABT_SCHED_EVENT_FREQ (or ABT_ENV_SCHED_EVENT_FREQ): Default event checking frequency for the scheduler. (Unsigned integer, Default: 50)
• ABT_SCHED_SLEEP_NSEC (or ABT_ENV_SCHED_SLEEP_NSEC): Default nanosleep value for scheduler sleep. (long, Default: 100)
• ABT_MUTEX_MAX_HANDOVERS (or ABT_ENV_MUTEX_MAX_HANDOVERS): Max mutex handovers within an ES before giving up the mutex. (Unsigned integer, Default: 64)
• ABT_MUTEX_MAX_WAKEUPS (or ABT_ENV_MUTEX_MAX_WAKEUPS): Max ULTs to wake up at once in ABT_mutex_unlock() or ABT_mutex_unlock_de(). (Unsigned integer, Default: 1)