# include/sys/async.h File Reference

`#include <event.h>`

## Defines
#define | _ASYNC_H 1
## Functions
void | atomic_begin ()
void | atomic_end ()
int16_t | continuation ()
int16_t | sch_continuation (int16_t resid, void(*app_handler)(event_t event, void *cbargs, void *context), void *resource, void *context)
int16_t | async_irqbind (int16_t intr_enum, void(*async_io_handler)(event_t event, void *cbargs, void *context), void *resource, void *context)
int16_t | async_irqunbind (int16_t intr_enum)
int16_t | continuation_close (int16_t id)

## Define Documentation

#define _ASYNC_H 1

## Function Documentation

int16_t async_irqbind | ( | int16_t | intr_enum,
|  | void(*)(event_t event, void *cbargs, void *context) | async_io_handler,
|  | void * | resource,
|  | void * | context |
| ) |  |  |

Bind a callback handler to a particular interrupt vector that are partially used by or shared with the kernel. Kernel services that requires interrupt context notification should use this to bind with notification handler. Note that this API is platform dependent and the handler will be fired within interrupt context. Once bind has called, subsequent call of this function will replace the old handler with a new handler.

Parameters:

  `[in]` | intr_enum | platform dependent interrupt enumeration number. Refer to InterruptTypesEnum for details.
  `[in]` | async_handler | the continuation callback handler that will be fired in interrupt context. If NULL is passed here, the call will fail.
  `[in]` | resource | pass NULL, will be ignored
  `[in]` | context | pass NULL, will be igonred

Returns:
  0 if succeed or EINVAL if invalid. Note errno is not used because this is in the interrupt context.

## Callback Descriptions

### async_handler

Parameters:

  `[in]` | event | type is ASYNC_IO in EventsEnum. subtype defines which interrupt is firing using InterruptTypesEnum defined in platform specific header files.
  `[in]` | cbargs | return NULL
  `[in]` | context | return NULL

Returns:
  None.

int16_t async_irqunbind | ( | int16_t | intr_enum | ) |

Unbind a previously installed callback handler to a particular interrupt vector that are partially used by or shared with the kernel. Note that this API is platform dependent and the handler will be fired within interrupt context. Once unbind has called, subsequent interrupts firing will not be notified.

Parameters:

  `[in]` | intr_enum | platform dependent interrupt enumeration number. Refer to InterruptTypesEnum for details.

Returns:
  0 if succeed or EINVAL if invalid. Note errno is not used because this is in the interrupt context.

void atomic_begin | ( |  | ) |

Disable global interrupt for the start of a critical section.

void atomic_end | ( |  | ) |

Enable global interrupt for the end of a critical section.

int16_t continuation | ( |  | ) |

Request a unique resource identifier that enables scheduling a continatuion from the interrupt context to Arch Rock's application context. Note this call is safe to be invoked in the interrupt context.

Returns:
  a non-zero resource identifiier if succeed or ENFILE all unique resource identifier has been used up. Note that errno is not used since this is in the interrupt context.

int16_t continuation_close | ( | int16_t | id | ) |

A system call that closes a continuation identifier so that it may be reused. This is safe to be called within the interrupt context.

Returns:
  0 on success, EINVAL for bad identifier, and EBUSY for waiting for an action to be executed before resource identifier can be freed.

int16_t sch_continuation | ( | int16_t | resid,
|  | void(*)(event_t event, void *cbargs, void *context) | app_handler,
|  | void * | resource,
|  | void * | context |
| ) |  |  |

To schedule a continatuion from the interrupt context to Arch Rock's application context. Note this call is safe to be invoked in the interrupt context.

Parameters:

  `[in]` | resid | a valid resouce id return by continuation().
  `[in]` | app_handler | the continuation callback handler that will be fired in application context. If NULL is passed here, the call will fail.
  `[in]` | resource | no requirement here.
  `[in]` | context | user context

Returns:
  0 if succeed or EBUSY if the resource with resid is busy or EINVAL if invalid parameters are passed. Note that errno is not used because this is in the interrupt context.

## Callback Descriptions

### app_handler

Parameters:

  `[in]` | event | Type is SCH_CONTINUATION in EventsEnum.
  `[in]` | cbargs | return resource in sch_continuation().
  `[in]` | context | return context in sch_continuation().

Returns:
  None.

## Code Example

      #include <sys/async.h>

      int16_t  g_resid;

      void __TIMER1_OVF_vect() {
        // interrupt context code
        g_resid = continuation();
        sch_continuation(g_resid, user_handler, NULL, NULL);
      }

      void user_handler(event_t event, void * cbaargs, void * context) {
        // ... user context action here
      }