lace.h

/* 
 * Copyright 2013-2016 Formal Methods and Tools, University of Twente
 * Copyright 2016-2017 Tom van Dijk, Johannes Kepler University Linz
 *
 * Licensed under the Apache License, Version 2.0 (the License);
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an AS IS BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#include <unistd.h>
#include <stdint.h>
#include <stdio.h>
#include <pthread.h> /* for pthread_t */

#ifndef __LACE_H__
#define __LACE_H__

#ifdef __has_include
#  if __has_include("lace_config.h")
#    include <lace_config.h>
#  else
#    define LACE_PIE_TIMES     0
#    define LACE_COUNT_TASKS   0
#    define LACE_COUNT_STEALS  0
#    define LACE_COUNT_SPLITS  0
#    define LACE_USE_HWLOC     0
#  endif
#endif

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/**
 * Using Lace.
 *
 * Optionally set the verbosity level with lace_set_verbosity.
 * Then call lace_init to initialize the system.
 * - lace_init(n_workers, deque_size);
 *   set both parameters to 0 for reasonable defaults, using all available cores.
 *
 * You can create Worker threads yourself or let Lace create threads with lace_startup.
 *
 * When creating threads yourself, call the following functions:
 *   - lace_init_worker to allocate and initialize the worker data structures
 *     this method returns when all workers have called lace_init_worker
 *   - lace_pin_worker (optional) to pin the thread and memory to a core
 * The main worker can now start its root task. All other workers:
 *   - lace_run_worker to perform work-stealing until the main worker calls lace_exit
 *
 * When letting Lace create threads with lace_startup
 * - Call lace_startup with a callback to create N threads.
 *   Returns after the callback has returned and all created threads are destroyed
 * - Call lace_startup without a callback to create N-1 threads.
 *   Returns control to the caller. When lace_exit is called, all created threads are terminated.
 */

/**
 * Type definitions used in the functions below.
 * - WorkerP contains the (private) Worker data
 * - Task contains a single Task
 */