/**
 * @file actl_thread.h
 * @brief Thread Queue에 필요한 기본적인 Interface
 * 
 * 주의할 점은 이는 Kernel영역에서 사용하는건 지원하지 않는다. 
 * 반드시 User영역에서만 사용해야 한다.
 *
 * @date Apr. 4, 2003
 * @author acetcom
 */

#ifndef __ACTL_THREAD_QUEUE_H__
#define __ACTL_THREAD_QUEUE_H__

#include <sys/time.h>
#include <sys/errno.h>
#include <stdlib.h>
#include <pthread.h>

#define ACTL_THREAD_QUEUE_SUCCESS 0

#define ACTL_THREAD_QUEUE_FAILURE 100
#define ACTL_THREAD_QUEUE_FAILURE_TIMEOUT (ACTL_THREAD_QUEUE_FAILURE+1)

#define ACTL_THREAD_QUEUE_TRUE 1
#define ACTL_THREAD_QUEUE_FALSE 0

#define ACTL_USEC_PER_SEC   (unsigned long long)(1000000)
#define ACTL_MSEC_PER_SEC   (unsigned long long)(1000)

typedef struct actl_thread_queue actl_thread_queue;

/**
 * @ingroup ACTL_THREAD_QUEUE
 * @struct actl_thread_queue
 * @brief Thread-Safe큐를 위한 기본 구조체이다.
 *
 * 고정적인 길이를 가진 데이터는 모두 actl_thread_queue로
 * 모두 구현할 수 있다.
 *
 * @code
 *
 * #include <stdio.h>
 * 
 * actl_thread_queue q;
 * 
 * #define ACTL_THREAD_QUEUE_NUMBER 50
 * 
 * void *producer_func(void *arg)
 * {
 *     int n = 0;
 * 
 *     while(1)
 *     {
 *     printf("put queue[%d] = %d\n", pthread_self(), n);
 *     fflush(stdout);
 *     q.put_queue(&q, &n, 2000 * ACTL_MSEC_PER_SEC);
 *     ++n;
 *     }
 * }
 * 
 * void *consumer_func(void *arg)
 * {
 *     int n;
 *     while(1)
 *     {
 *     q.get_queue(&q, &n, 2000 * ACTL_MSEC_PER_SEC);
 *     printf("get queue[%d] = %d\n", pthread_self(), n);
 *     fflush(stdout);
 *     }
 * }
 * 
 * int main()
 * {
 *     pthread_t t1, t2;
 *     int i;
 * 
 *     if (actl_thread_queue_init(&q) != ACTL_THREAD_QUEUE_SUCCESS)
 *     {
 *     fprintf(stderr, "ACTL Thread Initializing Failed\n");
 *     exit(-1);
 *     }
 * 
 *     q.create(&q, 3, sizeof(int));
 *     q.destroy(&q);
 * 
 *     pthread_create(&t2, NULL, consumer_func, NULL);
 *     for (i = 0; i < ACTL_THREAD_QUEUE_NUMBER; i++)
 *     {
 *     pthread_create(&t1, NULL, producer_func, NULL);
 *     }
 * 
 *     pthread_join(t1, NULL);
 *     pthread_join(t2, NULL);
 * }
 * @endcode
 */
struct actl_thread_queue
{
    /**
     * @brief 현재 큐에 들어있는 데이터를 보관하기 위한 메모리
     */
    char **queue_buffer;

    /**
     * @brief 큐에 넣고 빼낼 데이터의 길이
     */
    int obj_size;
    /**
     * @brief 큐의 크기
     */
    int queue_size;

    /**
     * @brief 큐의 읽기 위치
     * get_queue에 의해 큐를 읽을 때, 읽는 위치를 가리킨다.
     */
    int get_position;
    /**
     * @brief 큐의 쓰기 위치
     * put_queue에 의해 큐를 쓸 때, 쓰는 위치를 가리킨다.
     */
    int put_position;

    /**
     * @brief 큐가 차 있는지를 기록하는 플래그
     */
    int is_full;
    /**
     * @brief 큐가 비어 있는지를 기록하는 플래크
     */
    int is_empty;

    /**
     * @brief 여러 Thread가 put_queue할 때, 필요한 Lock
     */
    pthread_mutex_t lock1;

    /**
     * @brief Condition Variable을 위한 Lock
     */
    pthread_mutex_t lock2;
    /**
     * @brief 큐가 채워져 있을 때, 기다리기 위한 Condition Variable
     */
    pthread_cond_t cond1;
    /**
     * @brief 큐가 비워져 있을 때, 기다리기 위한 Condition Variable
     */
    pthread_cond_t cond2;

    /**
     * @brief 큐의 크기를 정하고, 읽기 위치와 쓰기 위치 등을 초기화 한다.
     *
     * @param queue_size 큐의 크기를 지정한다
     * @param obj_size 큐에 넣고 빼낼 데이터의 길이
     * @return 성공하면 ACTL_THREAD_QUEUE_SUCCESS를 리턴한다.
     */
    int (*create)(actl_thread_queue *q, int queue_size, int obj_size);
    /**
     * @brief 메모리들을 해제한다.
     * @return 성공하면 ACTL_THREAD_QUEUE_SUCCESS를 리턴한다.
     */
    int (*destroy)(actl_thread_queue *q);

    /**
     * @brief 사용자가 큐에 데이터를 넣을 때, 이를 이용한다.
     *
     * @param buf 큐에 넣을 데이터
     * @param sec 큐가 다 찬 경우 기다리는 시간(단위 : 1/1000000초)
     * @return 큐가 풀이고 기다리는 시간이 초과하면 false를 리턴한다.
     */
    int (*put_queue)(actl_thread_queue *q, void *buf, unsigned long long usec);
    /**
     * @brief 사용자가 큐로부터 데이터를 가져 올때, 이를 이용한다.
     *
     * @param buf 큐로 부터 가져온 데이터를 저장하는 메모리
     * @param sec 큐가 비어 있는 경우 기다리는 시간(단위 : 1/1000000초)
     * @return 큐가 풀이고 기다리는 시간이 초과하면 false를 리턴한다.
     */
    int (*get_queue)(actl_thread_queue *q, void *buf, unsigned long long usec);
};

/**
 * @ingroup ACTL_THREAD_QUEUE
 * @brief Thread Queue관련 Interface를 사용하기 위해 반드시 호출해야 한다.
 * @return 성공하면 ACTL_THREAD_QUEUE_SUCCESS를 리턴한다.
 */
int actl_thread_queue_init(actl_thread_queue *q);
/**
 * @ingroup ACTL_THREAD_QUEUE
 * @brief Thread Queue관련 Interface의 사용을 마치면 호출한다.
 * @return 성공하면 ACTL_THREAD_QUEUE_SUCCESS를 리턴한다.
 */
int actl_thread_queue_cleanup(actl_thread_queue *q);

#endif