tealet.h

Go to the documentation of this file.

 
/* A minimal coroutine package for C */
#ifndef _TEALET_H_
#define _TEALET_H_
 
#include <stddef.h>
 
/* Version information */
#define TEALET_VERSION_MAJOR 0
#define TEALET_VERSION_MINOR 4
#define TEALET_VERSION_PATCH 3
 
/* Version as a string */
#define TEALET_VERSION "0.4.3"
 
/* Version as a single number for comparisons (MMmmpp: Major, minor, patch) */
#define TEALET_VERSION_NUMBER ((TEALET_VERSION_MAJOR * 10000) + (TEALET_VERSION_MINOR * 100) + TEALET_VERSION_PATCH)
 
#ifdef WIN32
#if defined TEALET_EXPORTS
#define TEALET_API __declspec(dllexport)
#elif defined TEALET_IMPORTS
#define TEALET_API __declspec(dllimport)
#else
#define TEALET_API
#endif
#else /* win32 */
#define TEALET_API
#endif
 
typedef void *(*tealet_malloc_t)(size_t size, void *context);
typedef void (*tealet_free_t)(void *ptr, void *context);
typedef struct tealet_alloc_t {
  tealet_malloc_t malloc_p;
  tealet_free_t free_p;
  void *context;
} tealet_alloc_t;
 
#define TEALET_ALLOC_INIT_MALLOC                                                                                       \
  { (tealet_malloc_t) & malloc, (tealet_free_t)&free, 0 }
 
#define TEALET_ALLOC_MALLOC(alloc, size) (alloc)->malloc_p((size), (alloc)->context)
#define TEALET_ALLOC_FREE(alloc, ptr) (alloc)->free_p((ptr), (alloc)->context)
 
typedef struct tealet_t {
  struct tealet_t *main; /* pointer to the main tealet */
  void *extra;
  /* private fields follow */
} tealet_t;
 
typedef tealet_t *(*tealet_run_t)(tealet_t *current, void *arg);
 
#define TEALET_ERR_MEM -1     /* memory allocation failed */
#define TEALET_ERR_DEFUNCT -2 /* the target tealet is corrupt */
#define TEALET_ERR_UNFORKABLE                                                                                          \
  -3                            /* tealet cannot be forked (unbounded stack)                                           \
                                 */
#define TEALET_ERR_INVAL -4     /* invalid argument */
#define TEALET_ERR_INTEGRITY -5 /* current tealet violated stack-integrity boundary */
#define TEALET_ERR_PANIC -6     /* switched to main due to panic reroute from tealet_exit() */
 
/* configuration API structure versioning */
#define TEALET_CONFIG_VERSION_1 1
#define TEALET_CONFIG_CURRENT_VERSION TEALET_CONFIG_VERSION_1
 
/* stack integrity configuration flags */
#define TEALET_CONFIGF_STACK_INTEGRITY (1u << 0)
#define TEALET_CONFIGF_STACK_GUARD (1u << 1)
#define TEALET_CONFIGF_STACK_SNAPSHOT (1u << 2)
 
/* stack guard modes */
#define TEALET_STACK_GUARD_MODE_NONE 0
#define TEALET_STACK_GUARD_MODE_READONLY 1
#define TEALET_STACK_GUARD_MODE_NOACCESS 2
 
/* stack integrity failure policy */
#define TEALET_STACK_INTEGRITY_FAIL_ASSERT 0
#define TEALET_STACK_INTEGRITY_FAIL_ERROR 1
#define TEALET_STACK_INTEGRITY_FAIL_ABORT 2
 
/* conservative default upper bound for caller stack distance checks */
#define TEALET_DEFAULT_MAX_STACK_SIZE ((size_t)(16u * 1024u * 1024u))
 
typedef struct tealet_config_t {
  size_t size;
  unsigned int version;
  unsigned int flags;
  size_t stack_integrity_bytes;
  int stack_guard_mode;
  int stack_integrity_fail_policy;
  void *stack_guard_limit;
  size_t max_stack_size; /* max caller stack distance for sanity checks; 0 disables */
  unsigned int reserved[2];
} tealet_config_t;
 
/* Convenience initializer for configuration structs */
#define TEALET_CONFIG_INIT                                                                                             \
  {                                                                                                                    \
    sizeof(tealet_config_t), TEALET_CONFIG_CURRENT_VERSION, 0u, 0, TEALET_STACK_GUARD_MODE_NONE,                       \
        TEALET_STACK_INTEGRITY_FAIL_ASSERT, NULL, TEALET_DEFAULT_MAX_STACK_SIZE, {                                     \
      0u, 0u                                                                                                           \
    }                                                                                                                  \
  }
 
/* ----------------------------------------------------------------
 * Public API - core lifecycle and switching
 */
 
TEALET_API
tealet_t *tealet_initialize(tealet_alloc_t *alloc, size_t extrasize);
 
TEALET_API
void tealet_finalize(tealet_t *tealet);
 
TEALET_API
tealet_t *tealet_create(tealet_t *tealet, tealet_run_t run, void *stack_far);
 
TEALET_API
tealet_t *tealet_new(tealet_t *tealet, tealet_run_t run, void **parg, void *stack_far);
 
TEALET_API
int tealet_switch(tealet_t *target, void **parg);
 
/* Exit flags */
#define TEALET_EXIT_DEFAULT 0 /* Don't auto-delete */
#define TEALET_EXIT_DELETE 1  /* Auto-delete on exit */
#define TEALET_EXIT_DEFER 2   /* Defer exit to return statement */
 
TEALET_API
int tealet_exit(tealet_t *target, void *arg, int flags);
 
#define TEALET_FORK_DEFAULT 0
#define TEALET_FORK_SWITCH 1
TEALET_API
int tealet_fork(tealet_t *current, tealet_t **pother, void **parg, int flags);
 
TEALET_API
tealet_t *tealet_duplicate(tealet_t *tealet);
 
TEALET_API
void tealet_delete(tealet_t *target);
 
/* ----------------------------------------------------------------
 * Public API - status and query
 */
 
TEALET_API
tealet_t *tealet_current(tealet_t *tealet);
 
TEALET_API
tealet_t *tealet_previous(tealet_t *tealet);
 
TEALET_API
void **tealet_main_userpointer(tealet_t *tealet);
 
/* Tealet origin flags returned by tealet_get_origin(). */
#define TEALET_ORIGIN_MAIN_LINEAGE (1u << 0) /* main tealet, or fork-descended from main */
#define TEALET_ORIGIN_FORK (1u << 1)         /* tealet originated from tealet_fork() */
 
TEALET_API
unsigned int tealet_get_origin(tealet_t *tealet);
 
/* Status code: active tealet. */
#define TEALET_STATUS_ACTIVE 0
/* Status code: exited tealet. */
#define TEALET_STATUS_EXITED 1
/* Status code: defunct tealet. */
#define TEALET_STATUS_DEFUNCT -2
TEALET_API
int tealet_status(tealet_t *tealet);
 
TEALET_API
size_t tealet_get_stacksize(tealet_t *tealet);
 
TEALET_API
void *tealet_get_far(tealet_t *tealet);
 
/* Aggregate resource statistics for a main-tealet domain. */
typedef struct tealet_stats_t {
  /* Basic tealet counts */
  int n_active; /* number of active tealets (excluding main) */
  int n_total;  /* total tealets created (cumulative) */
 
  /* Memory usage statistics */
  size_t bytes_allocated;        /* Current heap allocation */
  size_t bytes_allocated_peak;   /* Peak heap allocation  */
  size_t blocks_allocated;       /* Current number of allocated stack blocks */
  size_t blocks_allocated_peak;  /* Peak number of allocated stack blocks */
  size_t blocks_allocated_total; /* Total allocation calls */
 
  /* stack memory storage statistics */
  size_t stack_bytes;          /* Bytes used for stack storage */
  size_t stack_bytes_expanded; /* Bytes used for stack if there were no reuse */
  size_t stack_bytes_naive;    /* Bytes used for stack if we stored stack naively */
  size_t stack_count;          /* Number of currently stored unique stacks */
  size_t stack_chunk_count;    /* Number of currently stored unique stack chunks */
} tealet_stats_t;
 
TEALET_API
void tealet_get_stats(tealet_t *t, tealet_stats_t *s);
 
TEALET_API
void tealet_reset_peak_stats(tealet_t *t);
 
/* ----------------------------------------------------------------
 * Public API - configuration
 */
 
TEALET_API
int tealet_set_far(tealet_t *tealet, void *far_boundary);
 
TEALET_API
int tealet_configure_get(tealet_t *tealet, tealet_config_t *config);
 
TEALET_API
int tealet_configure_set(tealet_t *tealet, tealet_config_t *config);
 
TEALET_API
int tealet_configure_check_stack(tealet_t *tealet, size_t stack_integrity_bytes);
 
/* ----------------------------------------------------------------
 * Public API - utility helpers
 */
 
TEALET_API
void *tealet_malloc(tealet_t *tealet, size_t s);
 
TEALET_API
void tealet_free(tealet_t *tealet, void *p);
 
/* functions for stack arithmetic.  Useful when deciding
 * if you want to start a new tealet, or when doing stack
 * spilling
 */
 
TEALET_API
ptrdiff_t tealet_stack_diff(void *a, void *b);
 
TEALET_API
void *tealet_stack_further(void *a, void *b);
 
TEALET_API
void *tealet_new_probe(tealet_t *dummy1, tealet_run_t dummy2, void **dummy3, void *dummy4);
 
/* Convenience macros */
#define TEALET_MAIN(t) ((t)->main)
#define TEALET_IS_MAIN(t) ((t) == TEALET_MAIN(t))
#define TEALET_CURRENT_IS_MAIN(t) (tealet_current(t) == TEALET_MAIN(t))
#define TEALET_IS_MAIN_LINEAGE(t) ((tealet_get_origin(t) & TEALET_ORIGIN_MAIN_LINEAGE) != 0)
#define TEALET_IS_FORK(t) ((tealet_get_origin(t) & TEALET_ORIGIN_FORK) != 0)
 
/* see if two tealets share the same MAIN, and can therefore be switched between
 */
#define TEALET_RELATED(t1, t2) (TEALET_MAIN(t1) == TEALET_MAIN(t2))
 
/* convenience access to a typecast extra pointer */
#define TEALET_EXTRA(t, tp) ((tp *)((t)->extra))
 
#endif /* _TEALET_H_ */