parallel.h

Go to the documentation of this file.

/*                      P A R A L L E L . H
 * BRL-CAD
 *
 * Copyright (c) 2004-2026 United States Government as represented by
 * the U.S. Army Research Laboratory.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * version 2.1 as published by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this file; see the file named COPYING for more
 * information.
 */
 
#ifndef BU_PARALLEL_H
#define BU_PARALLEL_H
 
#include "common.h"
 
#include <setjmp.h> /* for bu_setjmp */
 
#include "bu/defines.h"
 
__BEGIN_DECLS
 
/** @addtogroup bu_parallel
 * @brief
 * Thread based parallelism routines.
 */
/** @{ */
 
/**
 * MAX_PSW - The maximum number of processors that can be expected on
 * this hardware.  Used to allocate application-specific per-processor
 * tables at compile-time and represent a hard limit on the number of
 * processors/threads that may be spawned. The actual number of
 * available processors is found at runtime by calling bu_avail_cpus()
 */
#define MAX_PSW 4096 /* FIXME: just enough for 64 x 64 threads */
 
/**
 * @brief
 * subroutine to determine if we are multi-threaded
 *
 * This subroutine is separated off from parallel.c so that bu_bomb()
 * and others can call it, without causing either parallel.c or
 * semaphore.c to get referenced and thus causing the loader to drag
 * in all the parallel processing stuff from the vendor library.
 *
 */
 
/**
 * This routine is DEPRECATED, do not use it.  If you need a means to
 * determine when an application is running bu_parallel(), please
 * report this to our developers.
 *
 * Previously, this was a library-stateful way for bu_bomb() to tell
 * if a parallel application is running.  This routine now simply
 * returns zero all the time, which permits BU_SETJUMP() error
 * handling during bu_bomb().
 */
DEPRECATED BU_EXPORT extern int bu_is_parallel(void);
 
/**
 * Returns the CPU number of the current bu_parallel() invoked thread.
 *
 * This routine is intended for indexing into per-cpu memory buffers.
 * Values will be any number in the range of 0 to MAX_PSW.  They are
 * not guaranteed to be in any range except for non-parallel
 * applications which will have ID 0 for the main process's thread.
 */
BU_EXPORT extern int bu_parallel_id(void);
 
/**
 * Returns the OS thread ID of the calling thread.
 *
 * This routine is intended for diagnostic and unique ID purposes, not
 * for indexing into per-cpu memory buffers as values can be anything.
 */
BU_EXPORT extern int bu_thread_id(void);
 
 
/**
 * @brief
 * routines for parallel processing
 *
 * Machine-specific routines for portable parallel processing.
 *
 */
 
/**
 * Without knowing what the current UNIX "nice" value is, change to a
 * new absolute "nice" value.  (The system routine makes a relative
 * change).
 */
BU_EXPORT extern void bu_nice_set(int newnice);
 
/**
 * Return the maximum number of physical CPUs that are considered to
 * be available to this process now.
 */
BU_EXPORT extern size_t bu_avail_cpus(void);
 
 
/**
 * Create parallel threads of execution.
 *
 * This function creates (at most) 'ncpu' copies of function 'func'
 * all running in parallel, passing 'data' to each invocation.
 * Specifying ncpu=0 will specify automatic parallelization, invoking
 * parallel threads as cores become available.  This is particularly
 * useful during recursive invocations where the ncpu core count is
 * limited by the parent context.
 *
 * Locking and work dispatching are handled by 'func' using a
 * "self-dispatching" paradigm.  This means you must manually protect
 * shared data structures, e.g., via bu_semaphore_acquire().
 *
 * Lock-free execution is typically possible by creating data
 * containers with MAX_PSW elements as bu_parallel will never execute
 * more than that many threads.  Calling bu_parallel_id() provides the
 * id of the current thread, which can be used as an index into a
 * MAX_PSW per-cpu array.  The id is also passed as the func_cpu_id
 * parameter to the bu_parallel callback function.
 *
 * All invocations of the specified 'func' callback function are
 * passed two parameters: 1) it's assigned thread number and 2) a
 * shared 'data' pointer for application use.  Threads are assigned
 * increasing numbers, starting with zero.  Processes may also call
 * bu_parallel_id() to obtain their thread number.
 *
 * Threads created with bu_parallel() may specify utilization of
 * affinity locking to keep threads on a given physical CPU core.
 * This behavior can be enabled at runtime by setting the environment
 * variable LIBBU_AFFINITY=1.  Note that this option may increase or
 * even decrease performance, particularly on platforms with advanced
 * scheduling, so testing is recommended.
 *
 * This function will not return control until all invocations of the
 * subroutine are finished.
 *
 * In following is a working stand-alone example demonstrating how to
 * call the bu_parallel() interface.
 *
 * @code
 * void shoot_cells_in_series(int width, int height) {
 *   int i, j;
 *   for (i=0; i<height; i++) {
 *     for (j=0; j<width; j++) {
 *       printf("Shooting cell (%d, %d) on CPU %d\n", i, j, bu_parallel_id());
 *     }
 *   }
 * }
 *
 * void shoot_row_per_thread(int cpu, void *mydata) {
 *   int i, j, width;
 *   width = *(int *)mydata;
 *   for (i=0; i<width; i++) {
 *     printf("Shooting cell (%d, %d) on CPU %d\n", i, cpu, bu_parallel_id());
 *   }
 * }
 *
 * void shoot_cells_in_parallel(int width, int height) {
 *   bu_parallel(shoot_row_per_thread, height, &width);
 *   // we don't reach here until all threads complete
 * }
 *
 * int main(int ac, char *av[]) {
 *   int width = 4, height = 4;
 *   printf("\nShooting cells one at a time, 4x4 grid:\n");
 *   shoot_cells_in_series(width, height);
 *   printf("\nShooting cells in parallel with 4 threads, one per row:\n");
 *   shoot_cells_in_parallel(width, height);
 *   return 0;
 * }
 * @endcode
 */
BU_EXPORT extern void bu_parallel(void (*func)(int func_cpu_id, void *func_data), size_t ncpu, void *data);
 
 
/**
 * @brief
 * semaphore implementation
 *
 * Machine-specific routines for parallel processing.  Primarily for
 * handling semaphores to protect critical sections of code.
 *
 * The new paradigm: semaphores are referred to, not by a pointer, but
 * by a small integer.  This module is now responsible for obtaining
 * whatever storage is needed to implement each semaphore.
 *
 * Note that these routines can't use bu_log() for error logging,
 * because logging itself uses semaphores.
 */
 
/**
 * Process-wide semaphores needed by core library infrastructure have fixed
 * IDs.  They are valid during static initialization and do not depend on
 * library constructor or registration order.  IDs not listed here and below
 * BU_SEM_DYNAMIC_BASE are reserved for future core use.
 *
 * Keep this list as the single source for both the numeric constants and the
 * reserved name registry in libbu.
 */
#define BU_SEMAPHORE_RESERVED_LIST(_entry) \
    _entry(1, REGISTRY, "SEM_LOCK") \
    _entry(2, GENERAL, "BU_SEM_GENERAL") \
    _entry(3, SYSCALL, "BU_SEM_SYSCALL") \
    _entry(4, MAPPEDFILE, "BU_SEM_MAPPEDFILE") \
    _entry(5, THREAD, "BU_SEM_THREAD") \
    _entry(6, MALLOC, "BU_SEM_MALLOC") \
    _entry(7, DATETIME, "BU_SEM_DATETIME") \
    _entry(8, DIR, "BU_SEM_DIR") \
    _entry(9, LOG_HOOK, "BU_SEM_LOG_HOOK") \
    _entry(16, RT_WORKER, "RT_SEM_WORKER") \
    _entry(17, RT_RESULTS, "RT_SEM_RESULTS") \
    _entry(18, RT_MODEL, "RT_SEM_MODEL") \
    _entry(19, RT_TREE0, "RT_SEM_TREE0") \
    _entry(20, RT_TREE1, "RT_SEM_TREE1") \
    _entry(21, RT_TREE2, "RT_SEM_TREE2") \
    _entry(22, RT_TREE3, "RT_SEM_TREE3") \
    _entry(23, RT_DB_USES, "LIBRT_SEM_USES")
 
enum bu_semaphore_reserved_id {
    BU_SEM_ID_NONE = 0,
#define BU_SEMAPHORE_RESERVED_ENUM(_id, _symbol, _name) BU_SEM_ID_ ## _symbol = _id,
    BU_SEMAPHORE_RESERVED_LIST(BU_SEMAPHORE_RESERVED_ENUM)
#undef BU_SEMAPHORE_RESERVED_ENUM
    BU_SEM_DYNAMIC_BASE = 64
};
 
/**
 * Return the process-wide semaphore ID associated with name.  Registration is
 * thread-safe and idempotent: repeated registrations of the same name return
 * the same ID.  The registry keeps its own copy of name, and mappings remain
 * valid for the lifetime of the process, including across
 * bu_semaphore_free().
 *
 * Reserved core names return their fixed IDs.  Other names are assigned from
 * BU_SEM_DYNAMIC_BASE upward.
 *
 * A name must be non-NULL and non-empty.
 */
BU_EXPORT extern int bu_semaphore_register(const char *name);
 
 
/**
 * Define or update an application semaphore variable using the dynamic
 * process-wide name registry.  The assignment to x is not synchronized;
 * applications should use this during initialization before x is shared.
 *
 */
#define BU_SEMAPHORE_DEFINE(x) x = bu_semaphore_register(CPP_STR(x))
 
/**
 * This semaphore is intended for short-lived protection.
 *
 * It is provided for both library and application use, code that
 * doesn't call into a BRL-CAD library.
 */
BU_EXPORT extern int BU_SEM_GENERAL;
 
/**
 * This semaphore is intended to protect general system calls.
 *
 * It is provided for both library and application use, code that
 * doesn't call into a BRL-CAD library.
 */
BU_EXPORT extern int BU_SEM_SYSCALL;
 
/**
 * FIXME: this one shouldn't need to be global.
 */
BU_EXPORT extern int BU_SEM_MAPPEDFILE;
 
/*
 * Automatic restart capability in bu_bomb().  The return from
 * BU_SETJUMP is the return from the setjmp().  It is 0 on the first
 * pass through, and non-zero when re-entered via a longjmp() from
 * bu_bomb().  This is only safe to use in non-parallel applications.
 */
#define BU_SETJUMP setjmp((bu_setjmp_valid[bu_parallel_id()]=1, bu_jmpbuf[bu_parallel_id()]))
#define BU_UNSETJUMP (bu_setjmp_valid[bu_parallel_id()]=0)
 
/* These are global because BU_SETJUMP must be macro.  Please don't touch. */
BU_EXPORT extern int bu_setjmp_valid[MAX_PSW]; /* !0 = bu_jmpbuf is valid */
BU_EXPORT extern jmp_buf bu_jmpbuf[MAX_PSW];   /* for BU_SETJUMP() */
 
 
/**
 * Prepare 'nsemaphores' independent critical section semaphores.  Die
 * on error.
 *
 * Takes the place of 'n' separate calls to old RES_INIT().  Start by
 * allocating array of "struct bu_semaphores", which has been arranged
 * to contain whatever this system needs.
 *
 */
BU_EXPORT extern void bu_semaphore_init(unsigned int nsemaphores);
 
/**
 * Release all initialized native semaphore objects.  Registered name-to-ID
 * mappings are process-lifetime state and are retained, so existing handles
 * remain valid if semaphores are subsequently used again.
 *
 * The caller must ensure no other thread is using a semaphore while this
 * routine runs.
 *
 * FIXME: per hacking, rename to bu_semaphore_clear()
 */
BU_EXPORT extern void bu_semaphore_free(void);
 
BU_EXPORT extern void bu_semaphore_acquire(unsigned int i);
 
BU_EXPORT extern void bu_semaphore_release(unsigned int i);
 
/** @} */
 
__END_DECLS
 
#endif  /* BU_PARALLEL_H */
 
/*
 * Local Variables:
 * mode: C
 * tab-width: 8
 * indent-tabs-mode: t
 * c-file-style: "stroustrup"
 * End:
 * ex: shiftwidth=4 tabstop=8
 */