app_api.c File Reference

#include <config.h>
#include <unistd.h>
#include <isc/app.h>
#include <isc/magic.h>
#include <isc/mutex.h>
#include <isc/once.h>
#include <isc/util.h>

Go to the source code of this file.

Defines
#define	ISCAPI_APPMETHODS_VALID(m)   ISC_MAGIC_VALID(m, ISCAPI_APPMETHODS_MAGIC)
Functions
static void	initialize (void)
isc_result_t	isc_app_register (isc_appctxcreatefunc_t createfunc)
	Register a new application implementation and add it to the list of supported implementations. This function must be called when a different event library is used than the one contained in the ISC library.
isc_result_t	isc_appctx_create (isc_mem_t *mctx, isc_appctx_t **ctxp)
	Create an application context.
void	isc_appctx_destroy (isc_appctx_t **ctxp)
	Destroy an application context.
isc_result_t	isc_app_ctxstart (isc_appctx_t *ctx)
isc_result_t	isc_app_ctxrun (isc_appctx_t *ctx)
isc_result_t	isc_app_ctxonrun (isc_appctx_t *ctx, isc_mem_t *mctx, isc_task_t *task, isc_taskaction_t action, void *arg)
isc_result_t	isc_app_ctxsuspend (isc_appctx_t *ctx)
	This has the same behavior as isc_app_ctxsuspend().
isc_result_t	isc_app_ctxshutdown (isc_appctx_t *ctx)
void	isc_app_ctxfinish (isc_appctx_t *ctx)
void	isc_appctx_settaskmgr (isc_appctx_t *ctx, isc_taskmgr_t *taskmgr)
	Associate a task manager with an application context.
void	isc_appctx_setsocketmgr (isc_appctx_t *ctx, isc_socketmgr_t *socketmgr)
	Associate a socket manager with an application context.
void	isc_appctx_settimermgr (isc_appctx_t *ctx, isc_timermgr_t *timermgr)
	Associate a socket timer with an application context.
isc_result_t	isc_app_start (void)
	Start an ISC library application.
isc_result_t	isc_app_onrun (isc_mem_t *mctx, isc_task_t *task, isc_taskaction_t action, void *arg)
	Request delivery of an event when the application is run.
isc_result_t	isc_app_run ()
	Run an ISC library application.
isc_boolean_t	isc_app_isrunning ()
	Return if the ISC library application is running.
isc_result_t	isc_app_shutdown (void)
	Request application shutdown.
isc_result_t	isc_app_reload (void)
	Request application reload.
void	isc_app_finish (void)
	Finish an ISC library application.
void	isc_app_block (void)
	Indicate that a blocking operation will be performed.
void	isc_app_unblock (void)
	Indicate that a blocking operation is complete.
Variables
static isc_mutex_t	createlock
static isc_once_t	once = ISC_ONCE_INIT
static isc_appctxcreatefunc_t	appctx_createfunc = NULL
static isc_boolean_t	is_running = ISC_FALSE

---

Define Documentation

#define ISCAPI_APPMETHODS_VALID

(

m

)

ISC_MAGIC_VALID(m, ISCAPI_APPMETHODS_MAGIC)

Definition at line 34 of file app_api.c.

---

Function Documentation

static void initialize

(

void

)

[static]

Definition at line 37 of file app_api.c.

References createlock, isc_mutex_init, ISC_R_SUCCESS, and RUNTIME_CHECK.

Referenced by dns_db_create(), dns_db_register(), dns_db_unregister(), dns_lib_init(), dns_result_register(), dns_result_totext(), dst_result_register(), dst_result_totext(), isc_app_register(), isc_net_probeipv4(), isc_net_probeipv6(), isc_net_probeunix(), isc_random_get(), isc_random_seed(), isc_result_register(), isc_result_totext(), isc_socket_register(), isc_task_register(), isc_timer_register(), isccc_result_register(), isccc_result_totext(), pk11_initialize(), pk11_result_register(), and pk11_result_totext().

isc_result_t isc_app_register

(

isc_appctxcreatefunc_t

createfunc

)

Register a new application implementation and add it to the list of supported implementations. This function must be called when a different event library is used than the one contained in the ISC library.

Definition at line 42 of file app_api.c.

References appctx_createfunc, createlock, initialize(), isc_once_do, ISC_R_EXISTS, ISC_R_SUCCESS, LOCK, once, RUNTIME_CHECK, and UNLOCK.

isc_result_t isc_appctx_create	(	isc_mem_t *	mctx,
		isc_appctx_t **	ctxp
	)

Create an application context.

Requires:

• 'mctx' is a valid memory context.
• 'ctxp' != NULL && *ctxp == NULL.

Definition at line 58 of file app_api.c.

References appctx_createfunc, createlock, isc__appctx_create(), isc_bind9, LOCK, REQUIRE, and UNLOCK.

Referenced by dns_client_create().

void isc_appctx_destroy

(

isc_appctx_t **

ctxp

)

Destroy an application context.

Requires:

• '*ctxp' is a valid application context.

Ensures:

• *ctxp == NULL.

Definition at line 75 of file app_api.c.

References ENSURE, isc__appctx_destroy(), isc_bind9, ISCAPI_APPCTX_VALID, and REQUIRE.

Referenced by destroyclient(), and dns_client_create().

isc_result_t isc_app_ctxstart

(

isc_appctx_t *

ctx

)

Definition at line 87 of file app_api.c.

References isc_appmethods::ctxstart, isc__app_ctxstart(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, and REQUIRE.

Referenced by dns_client_create().

isc_result_t isc_app_ctxrun

(

isc_appctx_t *

ctx

)

Definition at line 97 of file app_api.c.

References isc_appmethods::ctxrun, isc__app_ctxrun(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, and REQUIRE.

Referenced by dns_client_request(), dns_client_resolve(), and dns_client_update().

isc_result_t isc_app_ctxonrun	(	isc_appctx_t *	ctx,
		isc_mem_t *	mctx,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg
	)

Definition at line 107 of file app_api.c.

References isc_appmethods::ctxonrun, isc__app_ctxonrun(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, and REQUIRE.

Referenced by resolve_done().

isc_result_t isc_app_ctxsuspend

(

isc_appctx_t *

ctx

)

This has the same behavior as isc_app_ctxsuspend().

Definition at line 120 of file app_api.c.

References isc_appmethods::ctxsuspend, isc__app_ctxsuspend(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, and REQUIRE.

Referenced by internal_update_callback(), localrequest_done(), resolve_done(), and suspend().

isc_result_t isc_app_ctxshutdown

(

isc_appctx_t *

ctx

)

Definition at line 130 of file app_api.c.

References isc_appmethods::ctxshutdown, isc__app_ctxshutdown(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, and REQUIRE.

void isc_app_ctxfinish

(

isc_appctx_t *

ctx

)

Definition at line 140 of file app_api.c.

References isc_appmethods::ctxfinish, isc__app_ctxfinish(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, and REQUIRE.

Referenced by destroyclient().

void isc_appctx_settaskmgr	(	isc_appctx_t *	ctx,
		isc_taskmgr_t *	taskmgr
	)

Associate a task manager with an application context.

This must be done before running tasks within the application context.

Requires:

• 'ctx' is a valid application context.
• 'taskmgr' is a valid task manager.

Definition at line 150 of file app_api.c.

References isc__appctx_settaskmgr(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, REQUIRE, and isc_appmethods::settaskmgr.

Referenced by isc_taskmgr_createinctx().

void isc_appctx_setsocketmgr	(	isc_appctx_t *	ctx,
		isc_socketmgr_t *	socketmgr
	)

Associate a socket manager with an application context.

This must be done before handling socket events within the application context.

Requires:

• 'ctx' is a valid application context.
• 'socketmgr' is a valid socket manager.

Definition at line 161 of file app_api.c.

References isc__appctx_setsocketmgr(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, REQUIRE, and isc_appmethods::setsocketmgr.

Referenced by isc_socketmgr_createinctx().

void isc_appctx_settimermgr	(	isc_appctx_t *	ctx,
		isc_timermgr_t *	timermgr
	)

Associate a socket timer with an application context.

This must be done before handling timer events within the application context.

Requires:

• 'ctx' is a valid application context.
• 'timermgr' is a valid timer manager. See isc_appctx_create() above.

Definition at line 172 of file app_api.c.

References isc__appctx_settimermgr(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, REQUIRE, and isc_appmethods::settimermgr.

Referenced by isc_timermgr_createinctx().

isc_result_t isc_app_start

(

void

)

Start an ISC library application.

Notes: This call should be made before any other ISC library call, and as close to the beginning of the application as possible.

Requires:

• 'ctx' is a valid application context (for app_ctxstart()).

Definition at line 183 of file app_api.c.

References isc__app_start(), isc_bind9, and ISC_R_NOTIMPLEMENTED.

Referenced by dns_test_begin(), main(), and setup().

isc_result_t isc_app_onrun	(	isc_mem_t *	mctx,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg
	)

Request delivery of an event when the application is run.

Requires:

• isc_app_start() has been called.
• 'ctx' is a valid application context (for app_ctxonrun()).

Returns: ISC_R_SUCCESS ISC_R_NOMEMORY

Definition at line 191 of file app_api.c.

References isc__app_onrun(), isc_bind9, and ISC_R_NOTIMPLEMENTED.

Referenced by ATF_TC_BODY(), main(), and ns_server_create().

isc_result_t isc_app_run

(

void

)

Run an ISC library application.

Notes:

• The caller (typically the initial thread of an application) will block until shutdown is requested. When the call returns, the caller should start shutting down the application.

Requires:

• isc_app_[ctx]start() has been called.

Ensures:

• Any events requested via isc_app_onrun() will have been posted (in FIFO order) before isc_app_run() blocks.
• 'ctx' is a valid application context (for app_ctxrun()).

Returns:

• ISC_R_SUCCESS Shutdown has been requested.
• ISC_R_RELOAD Reload has been requested.

Definition at line 201 of file app_api.c.

References is_running, isc__app_run(), isc_bind9, ISC_FALSE, ISC_R_NOTIMPLEMENTED, and ISC_TRUE.

Referenced by ATF_TC_BODY(), and main().

isc_boolean_t isc_app_isrunning

(

void

)

Return if the ISC library application is running.

Returns:

• ISC_TRUE App is running.
• ISC_FALSE App is not running.

Definition at line 216 of file app_api.c.

References is_running.

Referenced by get_address().

isc_result_t isc_app_shutdown

(

void

)

Request application shutdown.

Notes:

• It is safe to call isc_app_shutdown() multiple times. Shutdown will only be triggered once.

Requires:

• isc_app_[ctx]run() has been called.
• 'ctx' is a valid application context (for app_ctxshutdown()).

Returns:

• ISC_R_SUCCESS
• ISC_R_UNEXPECTED

Definition at line 221 of file app_api.c.

References isc__app_shutdown(), isc_bind9, and ISC_R_NOTIMPLEMENTED.

Referenced by all_done(), assignwork(), dighost_shutdown(), getinput(), load_done(), ns_control_docommand(), rndc_recvdone(), and rndc_senddone().

isc_result_t isc_app_reload

(

void

)

Request application reload.

Requires:

• isc_app_run() has been called.

Returns:

• ISC_R_SUCCESS
• ISC_R_UNEXPECTED

Definition at line 229 of file app_api.c.

References isc__app_reload(), isc_bind9, and ISC_R_NOTIMPLEMENTED.

void isc_app_finish

(

void

)

Finish an ISC library application.

Notes:

• This call should be made at or near the end of main().

Requires:

• isc_app_start() has been called.
• 'ctx' is a valid application context (for app_ctxfinish()).

Ensures:

• Any resources allocated by isc_app_start() have been released.

Definition at line 237 of file app_api.c.

References isc__app_finish(), and isc_bind9.

Referenced by cleanup_managers(), and main().

void isc_app_block

(

void

)

Indicate that a blocking operation will be performed.

Notes:

• If a blocking operation is in process, a call to isc_app_shutdown() or an external signal will abort the program, rather than allowing clean shutdown. This is primarily useful for reading user input.

Requires:

• isc_app_start() has been called.
• No other blocking operations are in progress.

Definition at line 245 of file app_api.c.

References isc__app_block(), and isc_bind9.

Referenced by do_next_command(), get_address(), get_addresses(), and get_next_command().

void isc_app_unblock

(

void

)

Indicate that a blocking operation is complete.

Notes:

• When a blocking operation has completed, return the program to a state where a call to isc_app_shutdown() or an external signal will shutdown normally.

Requires:

• isc_app_start() has been called.
• isc_app_block() has been called by the same thread.

Definition at line 253 of file app_api.c.

References isc__app_unblock(), and isc_bind9.

Referenced by do_next_command(), get_address(), get_addresses(), and get_next_command().

---

Variable Documentation

isc_mutex_t createlock [static]

Definition at line 29 of file app_api.c.

Referenced by initialize(), initialize_lock(), isc_app_register(), isc_appctx_create(), isc_hash_create(), isc_mem_register(), isc_socket_register(), isc_socketmgr_create(), and isc_socketmgr_createinctx().

isc_once_t once = ISC_ONCE_INIT [static]

Definition at line 30 of file app_api.c.

Referenced by dns_db_create(), dns_db_register(), dns_db_unregister(), dns_dlzcreate(), dns_dlzregister(), dns_dlzunregister(), dns_name_destroy(), fromtext_in_wks(), initialize(), isc__strerror(), isc_app_register(), isc_hash_create(), isc_mem_register(), isc_socket_register(), ns_lwresd_configure(), ns_lwresd_shutdown(), ns_stats_dump(), ns_statschannels_configure(), pk11_initialize(), and rbtdb_write_header().

isc_appctxcreatefunc_t appctx_createfunc = NULL [static]

Definition at line 31 of file app_api.c.

Referenced by isc_app_register(), and isc_appctx_create().

isc_boolean_t is_running = ISC_FALSE [static]

Definition at line 32 of file app_api.c.

Referenced by get_address(), isc_app_isrunning(), and isc_app_run().

---