---
title: "API for Callback Functions for `Network` and `WtNetwork` Structures"
author: Pavel N. Krivitsky
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  %\VignetteIndexEntry{API for Callback Functions for Network and WtNetwork Structures}
---

# Overview

## Types of storage and types of term

The callback API provides a way for a `Network` structure to signal precisely when a particular change (e.g., an edge toggle) is about to take place. It is intended to simplify and robustify the management of `u_` functions from the Terms API.

# Formal API definition

## New types

`void OnNetworkEdgeChange(Vertex, Vertex, void *, Network *)` and `void OnWtNetworkEdgeChange(Vertex, Vertex, double, void *, Network *)`, a callback function, compatible with `u_` functions and `Mu_` functions both (since a `void*` can be any pointer).

## New struct elements

### `Network` and `WtNetwork`

`OnNetworkEdgeChange **on_edge_change` and `OnWtNetworkEdgeChange **on_edge_change`: an array of pointers to callback functions.

`void **on_edge_change_payload`: an array of `void` pointers that get passed as the third argument to the corresponding `on_edge_change` function.

`unsigned int n_on_edge_change`: number of callbacks in the above two arrays.

`unsigned int max_on_edge_change`: the amount of space allocated for the above two arrays.

## New functions

`void AddOnNetworkEdgeChange(Network *nwp, OnNetworkEdgeChange u_func, void *payload, unsigned int pos)` and `void AddOnWtNetworkEdgeChange(WtNetwork *nwp, OnWtNetworkEdgeChange u_func, void *payload, unsigned int pos)`: Set a callback `u_func` to be called with argument `payload` whenever an edge in `nwp` is changed. Its position in the list (i.e., the order in which it is called) is set to be `pos` (with large `pos` truncated to indicate the last position).

`void DeleteOnNetworkEdgeChange(Network *nwp, OnNetworkEdgeChange u_func, void *payload)` and `void DeleteOnWtNetworkEdgeChange(WtNetwork *nwp, OnWTNetworkEdgeChange u_func, void *payload)`: Search the list of `nwp`'s callbacks for `u_func` and `payload` and delete the callback when it is found. (If it is not found, an immediate error is raised.)

## NB: Undefined Behaviour Sanitisers

Whereas before, it was possible to define a `u_func` with a specific payload type, e.g., `void u_myterm(Vertex tail, Vertex head, ModelTerm *mtp, Network *nwp)`, this will now trigger a warning by `clang-asan`, since the function signature expected will be different (i.e., `ModelTerm *` vs. `void *`). Terms and proposals therefore wrap their `u` functions, so this should be transparent to the developer, but anyone else using the API should be aware of this.