lf_token.h File Reference

Definitions for token objects, reference-counted wrappers around dynamically-allocated messages. More...

#include <stdlib.h>
#include <stdbool.h>

Go to the source code of this file.

Data Structures
struct	lf_port_base_t
	Base type for ports. More...
struct	lf_sparse_io_record_t
	A record of the subset of channels of a multiport that have present inputs. More...
struct	lf_token_t
	Token type for dynamically allocated arrays and structs sent as messages. More...
struct	token_template_t
	Base type for ports (lf_port_base_t) and actions (trigger_t), which can carry tokens. More...
struct	token_type_t
	Type information for tokens. More...

Typedefs
typedef struct lf_port_base_t	lf_port_base_t
	Base type for ports.
typedef struct lf_sparse_io_record_t	lf_sparse_io_record_t
	A record of the subset of channels of a multiport that have present inputs.
typedef struct lf_token_t	lf_token_t
	Token type for dynamically allocated arrays and structs sent as messages.
typedef struct self_base_t	self_base_t
typedef enum token_freed	token_freed
	Possible return values for _lf_done_using and _lf_free_token.
typedef struct token_template_t	token_template_t
	Base type for ports (lf_port_base_t) and actions (trigger_t), which can carry tokens.
typedef struct token_type_t	token_type_t
	Type information for tokens.

Enumerations
enum	token_freed { NOT_FREED = 0 , VALUE_FREED , TOKEN_FREED , TOKEN_AND_VALUE_FREED }
	Possible return values for _lf_done_using and _lf_free_token. More...

Functions
token_freed	_lf_done_using (lf_token_t *token)
	Decrement the reference count of the specified token.
void	_lf_free_all_tokens ()
	Free all tokens.
token_freed	_lf_free_token (lf_token_t *token)
	Free the specified token, if appropriate.
void	_lf_free_token_copies (void)
	Free token copies made for mutable inputs.
lf_token_t *	_lf_get_token (token_template_t *tmplt)
	Get a token for the specified template.
void	_lf_initialize_template (token_template_t *tmplt, size_t element_size)
	Initialize the specified template to contain a token that is an.
lf_token_t *	_lf_initialize_token (token_template_t *tmplt, size_t length)
	Return a token for storing an array of the specified length with new memory allocated (using calloc, so initialize to zero) for storing that array.
lf_token_t *	_lf_initialize_token_with_value (token_template_t *tmplt, void *value, size_t length)
	Return a token storing the specified value, which is assumed to be either a scalar (if length is 1) or an array of the specified length.
lf_token_t *	_lf_new_token (token_type_t *type, void *value, size_t length)
	Return a new token with the specified type, value, and length.
void	_lf_replace_template_token (token_template_t *tmplt, lf_token_t *newtoken)
	Replace the token in the specified template, if there is one, with a new one.
lf_token_t *	lf_new_token (void *port_or_action, void *val, size_t len)
	Return a new disassociated token with type matching the specified port or action and containing the specified value and length.
lf_token_t *	lf_writable_copy (lf_port_base_t *port)
	Return a writable copy of the token in the specified template.

Variables
int	_lf_count_token_allocations
	Counter used to issue a warning if memory is allocated for tokens and never freed.

Detailed Description

Definitions for token objects, reference-counted wrappers around dynamically-allocated messages.

Author

Edward A. Lee

This header file supports token objects, which are reference-counted wrappers around values that are carried by events scheduled on the event queue and held in ports and actions when the type is not a primitive type.

A token has type lf_token_t. It points to a value, a dynamically allocated chunk of memory on the heap. It has a length field, which enables its value to be interpreted as an array of the given length. It has a pointer to type (token_type_t), which has an element_size field specifying the size of each array element (or the size of the whole value if it is not an array and has length 1). The type also optionally has function pointers to a destructor and copy constructor. These must be specified if the payload (value) is a complex struct that cannot be freed by a simple call to free() or copied by a call to memcpy().

An instance of a port struct and trigger_t struct (an action or an input port) can be cast to token_template_t, which has a token_type_t field called type and a pointer to a token (which may be NULL). The same instance can also be cast to token_type_t, which has an element_size field and (possibly) function pointers to a destructor and copy constructor.

A "template token" is one pointed to by a token_template_t (an action or a port). This template token ensures that port an action values persist until they are overwritten, and hence they can be read at a tag even if not present. Such a token will persist in the template until it is overwritten by another token. Every token_template_t gets initialized with such a token. Before that token is used the first time, its reference count will be 0. Once it has been assigned a value, its reference count will be 1. When the token_template_t (port or action) is assigned a new value, if the reference count is 1, then the same token will be reused, and any previous value (payload) will be freed.

Typedef Documentation

self_base_t

typedef struct self_base_t self_base_t