path: root/src/cyn.h

/*
 * Copyright (C) 2018 "IoT.bzh"
 * Author José Bollo <jose.bollo@iot.bzh>
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


#pragma once

/**
 * Callback for entering asynchronousely the critical section
 * When called it receives the 'magic' argument given when
 * 'cyn_enter_async' was called.
 */
typedef void (on_enter_cb_t)(void *magic);

/**
 * Callback for being notified of changes in database
 * When called it receives the 'closure' argument given when
 * 'cyn_on_change_add' was called.
 */
typedef void (on_change_cb_t)(void *closure);

/**
 * Callback for receiving the result of a test or check
 * When called, receives the result 'value' of the request and
 * the 'closure' given when calling asynchronous query function.
 */
typedef void (on_result_cb_t)(void *closure, const data_value_t *value);

/**
 * Callback for listing data of the database.
 * When call receives the 'closure' given when 'cyn_list' is called
 * and the pair 'key', 'value' of the listed item.
 */
typedef void (list_cb_t)(
		void *closure,
		const data_key_t *key,
		const data_value_t *value);

/**
 * Callback for querying agents
 */
typedef int (agent_cb_t)(
		const char *name,
		void *agent_closure,
		const data_key_t *key,
		const char *value,
		on_result_cb_t *on_result_cb,
		void *on_result_closure);

/**
 * Enter in the critical recoverable section if possible
 *
 * @param magic a pointer not null that must be used in 'cyn_leave'
 * @return 0       entered
 *         -EBUSY  critical section already locked
 *         -EINVAL magic == NULL
 *
 * @see cyn_leave, cyn_enter_async
 */
extern
int
cyn_enter(
	const void *magic
);

/**
 * Leave the entered the critical recoverable section if possible
 *
 * @param magic a pointer not null that must be the one passed to
 *              'cyn_enter' or 'cyn_enter_async'
 * @param commit if true, the changes are committed to database, conversely
 *               if false, the changes made since entering the critical
 *               section are discarded
 * @return 0 success
 *         -EALREADY already unlocked
 *         -EINVAL magic == NULL
 *         -EPERM  magic doesn't match the magic that entered
 *         other negative codes: error when commiting the database
 *
 * @see cyn_enter, cyn_enter_async
 */
extern
int
cyn_leave(
	const void *magic,
	bool commit
);

/**
 * Enter asynchronously in the critical recoverable section if possible.
 * If the critical recoverable section is free, lock it with magic,
 * call the callback 'enter_cb' and returns 0. Otherwise, if the critical
 * section is already taken, the functions enqueue the entering request
 * and the callback will be called when the critical recoverable section is
 * available.
 *
 * @param enter_cb the entering callback
 * @param magic a pointer not null that must be used in 'cyn_leave'
 * @return 0  entered or or queued
 *         -ENOMEM critical section already locked but request can't be queued
 *         -EINVAL magic == NULL
 *
 * @see cyn_leave, cyn_enter
 */
extern
int
cyn_enter_async(
	on_enter_cb_t *enter_cb,
	void *magic
);

/**
 * Cancel a an asynchonous waiter to enter
 * @param enter_cb the enter callback of the waiter
 * @param magic the closure of the waiter
 * @return 0 if entry found and removed, -ENOENT if not found
 */
extern
int
cyn_enter_async_cancel(
	on_enter_cb_t *enter_cb,
	void *magic
);

/**
 * Add an observer to the list of observers
 *
 * @param on_change_cb callback receiving change events
 * @param closure closure of the callback
 * @return 0 success
 *         -ENOMEM can't queue the observer
 */
extern
int
cyn_on_change_add(
	on_change_cb_t *on_change_cb,
	void *closure
);

/**
 * Removes an on change observer
 * @param on_change_cb the callback of the observer
 * @param closure the closure of the observer
 * @return 0 if entry found and removed, -ENOENT if not found
 */
extern
int
cyn_on_change_remove(
	on_change_cb_t *on_change_cb,
	void *closure
);

/**
 * Set or add the rule key/value to the change list to commit
 * @param key the key of the rule
 * @param value the value of the rule for the key
 * @return 0 on success
 *         -EPERM if not locked in critical recoverable section
 *         other negative codes: error when queuing the change
 */
extern
int
cyn_set(
	const data_key_t *key,
	const data_value_t *value
);

/**
 * Drop any rule matching the key
 * @param key the key of the rule
 * @return 0 on success
 *         -EPERM if not locked in critical recoverable section
 *         other negative codes: error when queuing the change
 */
extern
int
cyn_drop(
	const data_key_t *key
);

extern
void
cyn_list(
	void *closure,
	list_cb_t *callback,
	const data_key_t *key
);

extern
int
cyn_query_async(
	on_result_cb_t *on_result_cb,
	void *closure,
	const data_key_t *key,
	int maxdepth
);

extern
int
cyn_test_async(
	on_result_cb_t *on_result_cb,
	void *closure,
	const data_key_t *key
);

extern
int
cyn_check_async(
	on_result_cb_t *on_result_cb,
	void *closure,
	const data_key_t *key
);

extern
int
cyn_agent_add(
	const char *name,
	agent_cb_t *agent_cb,
	void *closure
);

extern
int
cyn_agent_remove(
	const char *name
);

extern
void
cyn_changeid_reset(
);

extern
uint32_t
cyn_changeid(
);

extern
const char *
cyn_changeid_string(
);