/**
 * @file kc_queue.h
 * @brief Queue モジュールヘッダファイル
 * @copyright  2002 - 2023  Nomura Kei
 * @depends
 *	kc.h
 */
#ifndef KC_QUEUE_H
#define KC_QUEUE_H

#include <kc.h>

#ifdef __cplusplus
extern "C"
{
	namespace kc
	{
		using namespace std;
#endif

		/**
		 * キュー。
		 */
		typedef struct KcQueue_
		{

			/**
			 * キューに格納されている要素の数を返します。
			 *
			 * @param queue 対象キュー
			 * @return 対象キュー内の要素数
			 */
			int (*size)(struct KcQueue_ *queue);

			/**
			 * キューに要素がない場合に true を返します。
			 *
			 * @param queue 対象キュー
			 * @return 対象キューに要素が含まれていない場合は true
			 */
			bool (*is_empty)(struct KcQueue_ *queue);

			/**
			 * キューに指定された要素が含まれる場合に true を返します。
			 *
			 * @param queue 対象キュー
			 * @param element 要素
			 * @param size 要素のサイズ
			 */
			bool (*contains)(struct KcQueue_ *queue, const void *element, size_t size);

			/**
			 * キューに要素を追加します。
			 *
			 * @param queue   対象キュー
			 * @param element 追加する要素
			 * @param size    要素のサイズ
			 * @return true/false (追加成功/失敗)
			 */
			bool (*offer)(struct KcQueue_ *queue, const void *element, size_t size);

			/**
			 * キューより要素を取り出します。
			 * size が取り出す要素のサイズより小さい場合、element には、指定されたサイズまでがコピーされます。
			 * size には、実際の要素のサイズが格納されます。
			 *
			 * @param queue   対象キュー
			 * @param element 取り出された要素が格納されます。
			 * @param size    element のバッファサイズを指定します。また、取り出された要素のサイズが格納されます。
			 * @return true/false (要素の取り出し成功/失敗[要素がない])
			 */
			bool (*poll)(struct KcQueue_ *queue, void *element, size_t *size);

			/**
			 * キューより要素を取得しますが、削除しません。
			 *
			 * @param queue   対象キュー
			 * @param element 取り出された要素が格納されます。
			 * @param size    取り出された要素のサイズが格納されます。
			 * @return 要素へのポインタ
			 */
			void *(*peek)(struct KcQueue_ *queue, size_t *size);

			/**
			 * キューに要素を追加します。
			 * キューが一杯の状態で追加できない場合、追加できるまでブロックされます。
			 *
			 * @param queue   対象キュー
			 * @param element 追加する要素
			 * @param size    要素のサイズ
			 */
			void (*put)(struct KcQueue_ *queue, const void *element, size_t size);

			/**
			 * キューより要素を取り出します。
			 * 必要に応じて、要素が利用可能になるまでブロックされます。
			 * size が取り出す要素のサイズより小さい場合、element には、指定されたサイズまでがコピーされます。
			 * size には、実際の要素のサイズが格納されます。
			 *
			 * @param queue   対象キュー
			 * @param element 取り出された要素が格納されます。
			 * @param size    element のバッファサイズを指定します。また、取り出された要素のサイズが格納されます。
			 */
			void (*take)(struct KcQueue_ *queue, void *element, size_t *size);

			/**
			 * すべての要素をキューより削除します。
			 *
			 * @param queue 対象キュー
			 */
			void (*clear)(struct KcQueue_ *queue);

			/**
			 * キュー管理情報クリア用関数
			 *
			 * @param queue 対象キュー
			 */
			void (*cleanup_info)(struct KcQueue_ *queue);

			/**
			 * キュー管理情報
			 * 本オブジェクトはリスト実装者が利用するための情報へのポインタとなります。
			 */
			void *_info;

		} KcQueue;

		/**
		 * Queue を構築します。
		 * size に 0 が指定された場合、キューサイズ INT_MAX として処理されます。
		 *
		 * @param size キューのサイズ
		 * @return Queue
		 */
		KcQueue *KcQueue_new(int size);

		/**
		 * KcQueue を破棄します。
		 *
		 * @param queue 破棄するキュー
		 */
		void KcQueue_delete(KcQueue *queue);

#ifdef __cplusplus
	} // namespace kc
} // extern "C"
#endif
#endif // KC_QUEUE_H