Execution context (xctx)

Files
file	afw_xctx.h
	Adaptive Framework Execution Context (xctx) Implementation Header.

Data Structures
struct	afw_xctx_evaluation_stack_entry_s
	The execution context (xctx) evaluation stack entry. More...
struct	afw_xctx_qualifier_stack_entry_s

Macros
#define	AFW_XCTX_Q_NAME_BASE   "base"
#define	AFW_XCTX_s_NAME_BASE   afw_s_base
#define	AFW_XCTX_Q_NAME_REQUEST_THREAD   "request_thread"
#define	AFW_XCTX_s_NAME_REQUEST_THREAD   afw_s_request_thread
#define	AFW_XCTX_Q_NAME_REQUEST_SESSION   "request_session"
#define	AFW_XCTX_s_NAME_REQUEST_SESSION   afw_s_request_session
#define	afw_xctx_evaluation_stack_push_value(VALUE, xctx)
	Push VALUE onto execution stack. More...
#define	afw_xctx_evaluation_stack_push_parameter_number(PARAMETER_NUMBER, xctx)
	Push PARAMETER_NUMBER onto execution stack. More...
#define	afw_xctx_evaluation_stack_pop(xctx)
	Pop top PARAMETER_NUMBER or VALUE off execution stack. More...
#define	afw_xctx_evaluation_stack_pop_value(xctx)   afw_stack_pop(xctx->evaluation_stack, xctx)
	Pop top VALUE off execution stack. More...
#define	afw_xctx_evaluation_stack_pop_parameter_number(xctx)
	Pop top PARAMETER_NUMBER off execution stack. More...
#define	afw_xctx_evaluation_stack_save_top(xctx)
	Save top of stack. More...
#define	afw_xctx_evaluation_stack_restore_top(xctx)   xctx->evaluation_stack->top = evaluation_stack_save_top
	Save top of stack. More...
#define	afw_xctx_calloc(size, xctx)    afw_pool_calloc((xctx)->p, (size), (xctx))
	Macro to allocate cleared memory in xctx's pool. More...
#define	afw_xctx_calloc_type(type, xctx)    (type *) afw_pool_calloc((xctx)->p, sizeof(type), (xctx))
	Macro to allocate cleared memory to hold type in xctx's pool. More...
#define	afw_xctx_malloc(size, xctx)    afw_pool_malloc((xctx)->p, (size), (xctx))
	Macro to allocate uncleared memory in xctx's pool. More...
#define	afw_xctx_malloc_type(type, xctx)    (type *) afw_pool_malloc((xctx)->p, sizeof(type), (xctx))
	Macro to allocate uncleared memory to hold type in xctx's pool. More...
#define	AFW_XCTX_SECURE_BEGIN
	Begin a section this can only use secure context variables. More...
#define	AFW_XCTX_SECURE_END
	End a section this can only use secure context variables. More...
#define	AFW_XCTX_AUTHORIZATION_MODE_BEGIN(modeId)
	Macro to begin an authorization mode change section. More...
#define	AFW_XCTX_AUTHORIZATION_MODE_END
	Macro to end an authorization xctx mode change section. More...

Functions
	AFW_STACK_STRUCT (afw_xctx_evaluation_stack_s, afw_xctx_evaluation_stack_entry_t)
afw_xctx_t *	afw_xctx_create (const afw_utf8_t *name, afw_integer_t number, afw_xctx_t *xctx)
	Create an Adaptive Framework xctx. More...
afw_boolean_t	afw_xctx_environment_is_terminating (afw_xctx_t *xctx)
	Test for environment terminating. More...
const afw_value_t *	afw_xctx_get_qualified_variable (const afw_utf8_t *qualifier, const afw_utf8_t *name, afw_xctx_t *xctx)
	Get a variable from xctx stack. More...
void	afw_xctx_define_variable (const afw_utf8_t *name, const afw_value_t *value, afw_xctx_t *xctx)
	Defined a variable in current xctx frame. More...
void	afw_xctx_set_defined_variable (const afw_utf8_t *name, const afw_value_t *value, afw_xctx_t *xctx)
	Set a defined variable in xctx. More...
void	afw_xctx_set_local_variable (const afw_utf8_t *name, const afw_value_t *value, afw_xctx_t *xctx)
	Set a variable then current xctx frame. More...
int	afw_xctx_begin_stack_frame (afw_xctx_t *xctx)
	Begin stack frame. More...
void	afw_xctx_end_stack_frame (int top, afw_xctx_t *xctx)
	Set stack top. More...
int	afw_xctx_get_qualifier_stack_top (afw_xctx_t *xctx)
	Get qualifier stack top. More...
void	afw_xctx_set_qualifier_stack_top (int top, afw_xctx_t *xctx)
	Set stack top index. More...
void	afw_xctx_push_qualifiers_object (const afw_object_t *context_object, afw_boolean_t secure, const afw_pool_t *p, afw_xctx_t *xctx)
	Push qualifiers object on to stack. More...
afw_xctx_qualifier_stack_entry_t *	afw_xctx_push_qualifier (const afw_utf8_t *qualifier, const afw_object_t *qualifier_object, afw_boolean_t secure, afw_xctx_get_variable_t get, void *data, const afw_pool_t *p, afw_xctx_t *xctx)
	Push qualifier on to stack. More...
void	afw_xctx_push_qualifier_object (const afw_utf8_t *qualifier_name, const afw_object_t *qualifier_object, afw_boolean_t secure, const afw_pool_t *p, afw_xctx_t *xctx)
	Push qualifier object on to stack. More...
	afw_xctx_qualifier_object_create (const afw_utf8_t *qualifier, afw_boolean_t for_testing, const afw_pool_t *p, afw_xctx_t *xctx)
	Create object to access active variables for a qualifier. More...
	afw_xctx_qualifiers_object_create (afw_boolean_t for_testing, const afw_pool_t *p, afw_xctx_t *xctx)
	Create object to access active qualified variables. More...

Detailed Description

Adaptive Framework Execution Context (xctx).

Macro Definition Documentation

AFW_XCTX_AUTHORIZATION_MODE_BEGIN

#define AFW_XCTX_AUTHORIZATION_MODE_BEGIN

(

modeId

)

Value:

const afw_value_t *this_PREVIOUS_MODE = \
    xctx->mode = afw_authorization_mode_id_ ## modeId ## _value; \
AFW_TRY

Macro to begin an authorization mode change section.

Parameters

modeId

(core, intermediate, or user).

The variable name of the current xctx must be named xctx.

Usage:

AFW_XCTX_AUTHORIZATION_MODE_BEGIN(intermediate) { ... code } AFW_XCTX_AUTHORIZATION_MODE_END;

Definition at line 507 of file afw_xctx.h.

AFW_XCTX_AUTHORIZATION_MODE_END

#define AFW_XCTX_AUTHORIZATION_MODE_END

Value:

AFW_FINALLY { \
    xctx->mode =  this_PREVIOUS_MODE; \
} \
AFW_ENDTRY

Macro to end an authorization xctx mode change section.

See AFW_XCTX_AUTHORIZATION_MODE_BEGIN for usage.

Definition at line 518 of file afw_xctx.h.

afw_xctx_calloc

#define afw_xctx_calloc	(		size,
			xctx
	)		afw_pool_calloc((xctx)->p, (size), (xctx))

Macro to allocate cleared memory in xctx's pool.

Parameters

size	of memory to allocate.
xctx	of caller.

Returns

Pointer to memory allocated.

Definition at line 185 of file afw_xctx.h.

afw_xctx_calloc_type

#define afw_xctx_calloc_type	(		type,
			xctx
	)		(type *) afw_pool_calloc((xctx)->p, sizeof(type), (xctx))

Macro to allocate cleared memory to hold type in xctx's pool.

Parameters

type	to allocate.
xctx	of caller.

Returns

Pointer to memory allocated cast to pointer of type.

This is a helper macro to call afw_xctx_calloc() to allocate memory for a specified type and cast the return pointer to a pointer to that type.

Definition at line 199 of file afw_xctx.h.

afw_xctx_evaluation_stack_pop

#define afw_xctx_evaluation_stack_pop

(

xctx

)

Value:

if (xctx->evaluation_stack->top->entry_id == &afw_s_parameter_number) { \
    afw_stack_pop(xctx->evaluation_stack, xctx); \
} \
afw_stack_pop(xctx->evaluation_stack, xctx)

Pop top PARAMETER_NUMBER or VALUE off execution stack.

Parameters

xctx	of caller.

Definition at line 100 of file afw_xctx.h.

afw_xctx_evaluation_stack_pop_parameter_number

#define afw_xctx_evaluation_stack_pop_parameter_number

(

xctx

)

Value:

afw_stack_pop(xctx->evaluation_stack, xctx); \
afw_stack_pop(xctx->evaluation_stack, xctx)

Pop top PARAMETER_NUMBER off execution stack.

Parameters

xctx	of caller.

Use only when you're positive top of stack is PARAMETER_NUMBER.

Definition at line 124 of file afw_xctx.h.

afw_xctx_evaluation_stack_pop_value

#define afw_xctx_evaluation_stack_pop_value

(

xctx

)

afw_stack_pop(xctx->evaluation_stack, xctx)

Pop top VALUE off execution stack.

Parameters

xctx	of caller.

Use only when you're positive top of stack is VALUE.

Definition at line 113 of file afw_xctx.h.

afw_xctx_evaluation_stack_push_parameter_number

#define afw_xctx_evaluation_stack_push_parameter_number	(		PARAMETER_NUMBER,
			xctx
	)

Value:

    afw_stack_push_direct(xctx->evaluation_stack, xctx); \
    (xctx)->evaluation_stack->top->parameter_number =PARAMETER_NUMBER; \
    afw_stack_push_direct(xctx->evaluation_stack, xctx); \
    (xctx)->evaluation_stack->top->entry_id = &afw_s_parameter_number

Push PARAMETER_NUMBER onto execution stack.

Parameters

PARAMETER_NUMBER.
xctx	of caller.

Definition at line 88 of file afw_xctx.h.

afw_xctx_evaluation_stack_push_value

#define afw_xctx_evaluation_stack_push_value	(		VALUE,
			xctx
	)

Value:

    afw_stack_push_direct(xctx->evaluation_stack, xctx); \
    (xctx)->evaluation_stack->top->value = VALUE

Push VALUE onto execution stack.

Parameters

VALUE.
xctx	of caller.

Returns

Don't use.

Definition at line 78 of file afw_xctx.h.

afw_xctx_evaluation_stack_restore_top

#define afw_xctx_evaluation_stack_restore_top

(

xctx

)

xctx->evaluation_stack->top = evaluation_stack_save_top

Save top of stack.

Parameters

xctx	of caller.

Definition at line 142 of file afw_xctx.h.

afw_xctx_evaluation_stack_save_top

#define afw_xctx_evaluation_stack_save_top

(

xctx

)

Value:

afw_xctx_evaluation_stack_entry_t *evaluation_stack_save_top = \
xctx->evaluation_stack->top

Save top of stack.

Parameters

xctx	of caller.

Definition at line 133 of file afw_xctx.h.

afw_xctx_malloc

#define afw_xctx_malloc	(		size,
			xctx
	)		afw_pool_malloc((xctx)->p, (size), (xctx))

Macro to allocate uncleared memory in xctx's pool.

Parameters

size	of memory to allocate.
xctx	of caller.

Returns

Pointer to memory allocated.

Definition at line 209 of file afw_xctx.h.

afw_xctx_malloc_type

#define afw_xctx_malloc_type	(		type,
			xctx
	)		(type *) afw_pool_malloc((xctx)->p, sizeof(type), (xctx))

Macro to allocate uncleared memory to hold type in xctx's pool.

Parameters

type	to allocate.
xctx	of caller.

Returns

Pointer to memory allocated cast to pointer of type.

This is a helper macro to call afw_pool_malloc() to allocate memory for a specified type and cast the return pointer to a pointer to that type.

Definition at line 223 of file afw_xctx.h.

AFW_XCTX_Q_NAME_BASE

#define AFW_XCTX_Q_NAME_BASE   "base"

Name of base xctx.

Definition at line 31 of file afw_xctx.h.

AFW_XCTX_Q_NAME_REQUEST_SESSION

#define AFW_XCTX_Q_NAME_REQUEST_SESSION   "request_session"

Name of request session xctx.

Definition at line 43 of file afw_xctx.h.

AFW_XCTX_Q_NAME_REQUEST_THREAD

#define AFW_XCTX_Q_NAME_REQUEST_THREAD   "request_thread"

Name of request thread xctx.

Definition at line 37 of file afw_xctx.h.

AFW_XCTX_s_NAME_BASE

#define AFW_XCTX_s_NAME_BASE   afw_s_base

Name of base xctx.

Definition at line 34 of file afw_xctx.h.

AFW_XCTX_s_NAME_REQUEST_SESSION

#define AFW_XCTX_s_NAME_REQUEST_SESSION   afw_s_request_session

Name of request session xctx.

Definition at line 46 of file afw_xctx.h.

AFW_XCTX_s_NAME_REQUEST_THREAD

#define AFW_XCTX_s_NAME_REQUEST_THREAD   afw_s_request_thread

Name of request thread xctx.

Definition at line 40 of file afw_xctx.h.

AFW_XCTX_SECURE_BEGIN

#define AFW_XCTX_SECURE_BEGIN

Value:

do { \
    afw_boolean_t this_SCOPE_save_secure = xctx->secure; \
    xctx->secure = true; \
    AFW_TRY

Begin a section this can only use secure context variables.

Parameters

xctx	of caller.

The variable name of the current xctx must be named xctx.

Usage:

AFW_XCTX_SECURE_BEGIN { ... code that can only use secure context variables } AFW_XCTX_SECURE_END;

Definition at line 239 of file afw_xctx.h.

AFW_XCTX_SECURE_END

#define AFW_XCTX_SECURE_END

Value:

    AFW_FINALLY { \
        xctx->secure = this_SCOPE_save_secure; \
    } \
    AFW_ENDTRY; \
} while(0)

End a section this can only use secure context variables.

Definition at line 250 of file afw_xctx.h.

Function Documentation

afw_xctx_begin_stack_frame()

int afw_xctx_begin_stack_frame

(

afw_xctx_t *

xctx

)

Begin stack frame.

Parameters

xctx	of caller.

Returns

Parameter to pass to end_stack_frame.

Definition at line 329 of file afw_xctx.h.

afw_xctx_create()

afw_xctx_t* afw_xctx_create	(	const afw_utf8_t *	name,
		afw_integer_t	number,
		afw_xctx_t *	xctx
	)

Create an Adaptive Framework xctx.

Parameters

name	of xctx.
number	that is unique within the life of this Adaptive Framework application for this xctx name.
xctx	of caller. This will be xctx's parent.

Call each time a new xctx is needed with a shorter lifetime. For example, a server xctx with a shorter lifetime request_session xctx. Calling the release method will release all resources allocated in the xctx including any children xctxs. Call afw_environment_create() to create the initial xctx.

The xctx authorization mode is set to user. Use AFW_XCTX_AUTHORIZATION_MODE_BEGIN/END to change it.

Definition at line 145 of file afw_xctx.c.

afw_xctx_define_variable()

void afw_xctx_define_variable	(	const afw_utf8_t *	name,
		const afw_value_t *	value,
		afw_xctx_t *	xctx
	)

Defined a variable in current xctx frame.

Deprecated:

Parameters

name	Name of variable.
value	Value to set.
xctx	of caller.

Returns

value or NULL if not found.

Define a variable in the current xctx frame with an initial value. If the variable is already defined in the current xctx frame, an error is thrown.

Definition at line 235 of file afw_xctx.c.

afw_xctx_end_stack_frame()

void afw_xctx_end_stack_frame	(	int	top,
		afw_xctx_t *	xctx
	)

Set stack top.

Parameters

top	Value returned from corresponding afw_xctx_begin_stack_frame().
xctx	of caller.

Definition at line 343 of file afw_xctx.h.

afw_xctx_environment_is_terminating()

afw_boolean_t afw_xctx_environment_is_terminating

(

afw_xctx_t *

xctx

)

Test for environment terminating.

Parameters

xctx	of caller.

Returns

true if environment terminating.

Definition at line 173 of file afw_xctx.h.

afw_xctx_get_qualified_variable()

const afw_value_t* afw_xctx_get_qualified_variable	(	const afw_utf8_t *	qualifier,
		const afw_utf8_t *	name,
		afw_xctx_t *	xctx
	)

Get a variable from xctx stack.

Parameters

qualifier	or NULL if unqualified. (NULL is deprecated)
name	of variable.
xctx	of caller.

Returns

value or NULL if not found.

The stack is searched from newest to oldest.

Definition at line 176 of file afw_xctx.c.

afw_xctx_get_qualifier_stack_top()

int afw_xctx_get_qualifier_stack_top

(

afw_xctx_t *

xctx

)

Get qualifier stack top.

Parameters

xctx	of caller.

Returns

Stack top index.

Definition at line 316 of file afw_xctx.c.

afw_xctx_push_qualifier()

afw_xctx_qualifier_stack_entry_t* afw_xctx_push_qualifier	(	const afw_utf8_t *	qualifier,
		const afw_object_t *	qualifier_object,
		afw_boolean_t	secure,
		afw_xctx_get_variable_t	get,
		void *	data,
		const afw_pool_t *	p,
		afw_xctx_t *	xctx
	)

Push qualifier on to stack.

Parameters

qualifier	or NULL.
qualifier_object.
secure	access to this qualifier is allowed.
get	routine or NULL.
data	to be passed to get/set.
p	used while evaluating variable values.
xctx	of caller.

Returns

New qualifier stack entry.

The "get" function is the fastest way to get the value of a known variable for this pushed qualifier. The qualifier_object is used when the get_next_property() method is needed.

Never specify secure true if source of context is a client. A secure context is used for access control and other server side configured evaluates.

This function should use AFW_TRY to restore top.

top = afw_xctx_get_qualifier_stack_top(xctx); AFW_TRY (xctx) { afw_xctx_push_qualifier(...); ... do something } AFW_FINALLY { afw_xctx_set_qualifier_stack_top(top, xctx); }

Todo:

FIXME: add support for qualifier object.

Definition at line 359 of file afw_xctx.c.

afw_xctx_push_qualifier_object()

void afw_xctx_push_qualifier_object	(	const afw_utf8_t *	qualifier_name,
		const afw_object_t *	qualifier_object,
		afw_boolean_t	secure,
		const afw_pool_t *	p,
		afw_xctx_t *	xctx
	)

Push qualifier object on to stack.

Parameters

qualifier_name	or NULL.
qualifier_object	whose properties will be variables.
secure	access to this qualifier is allowed.
p	used while evaluating variable values.
xctx	of caller.

Returns

Stack top.

Never specify secure true if source of context is a client. A secure context is used for access control and other server side configured evaluates.

See afw_xctx_push_qualifier() for use pattern.

Definition at line 406 of file afw_xctx.c.

afw_xctx_push_qualifiers_object()

void afw_xctx_push_qualifiers_object	(	const afw_object_t *	context_object,
		afw_boolean_t	secure,
		const afw_pool_t *	p,
		afw_xctx_t *	xctx
	)

Push qualifiers object on to stack.

Parameters

context_object.
secure	access to this qualifier is allowed.
p	used while evaluating variable values.
xctx	of caller.

Returns

Stack top.

Context object is an object whose properties are objects with a name of a qualifier. Each of the qualifier objects contains properties that are variable name/adaptive value pairs.

Never specify secure true if source of context is a client. A secure context is used for access control and other server side configured evaluates.

See afw_xctx_push_qualifier() for use pattern.

Definition at line 336 of file afw_xctx.c.

afw_xctx_qualifier_object_create()

afw_xctx_qualifier_object_create	(	const afw_utf8_t *	qualifier,
		afw_boolean_t	for_testing,
		const afw_pool_t *	p,
		afw_xctx_t *	xctx
	)

Create object to access active variables for a qualifier.

Parameters

qualifier_name.
for_testing
p	to use.
xctx	of caller.

Returns

qualifier object.

Definition at line 38 of file afw_xctx_qualifier_object.c.

afw_xctx_qualifiers_object_create()

afw_xctx_qualifiers_object_create	(	afw_boolean_t	for_testing,
		const afw_pool_t *	p,
		afw_xctx_t *	xctx
	)

Create object to access active qualified variables.

Parameters

for_testing
p	to use.
xctx	of caller.

Returns

qualifier object.

Definition at line 65 of file afw_xctx_qualifier_object.c.

afw_xctx_set_defined_variable()

void afw_xctx_set_defined_variable	(	const afw_utf8_t *	name,
		const afw_value_t *	value,
		afw_xctx_t *	xctx
	)

Set a defined variable in xctx.

Deprecated:

Parameters

name	Name of variable.
value	Value to set.
xctx	of caller.

Returns

value or NULL if not found.

The most recently defined named variable in xctx will be set to the value. If the variable is not found or const an error is thrown.

Definition at line 263 of file afw_xctx.c.

afw_xctx_set_local_variable()

void afw_xctx_set_local_variable	(	const afw_utf8_t *	name,
		const afw_value_t *	value,
		afw_xctx_t *	xctx
	)

Set a variable then current xctx frame.

Parameters

name	Name of variable.
value	Value to set.
xctx	of caller.

Returns

value or NULL if not found.

The current stack frame will be searched for an entry with the same name. If found, the value of that entry will be set. If not found, a new entry will be added.

Definition at line 289 of file afw_xctx.c.

afw_xctx_set_qualifier_stack_top()

void afw_xctx_set_qualifier_stack_top	(	int	top,
		afw_xctx_t *	xctx
	)

Set stack top index.

Parameters

top	returned from corresponding afw_xctx_get_qualifier_stack_top().
xctx	of caller.

Definition at line 325 of file afw_xctx.c.