CCThreadedQueue.h

Go to the documentation of this file.

/*
 * Copyright 2017 Brendan Bruner
 *
 * 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.
 *
 * bbruner@ualberta.ca
 * March 22, 2017
 */
#ifndef UTIL_CCTHREADEDQUEUE_H_
#define UTIL_CCTHREADEDQUEUE_H_

#include <Class.h>
#include <CError.h>
#include <CIQueue.h>
#include <COS.h>

#ifdef __unix__
#include <pthread.h>
#else
#error "Unsupported operating system. Do not use CCThreadedQueue.h/c"
#endif


/************************************************************************/
/* Error codes.                             */
/************************************************************************/
typedef enum
{
    /* Enum values must have one to one mapping with values of
     * CIQueueError. Add error codes with increasing values, but
     * do not change existing values.
     */
    CCTQUEUE_OK = 0,
    CCTQUEUE_ERR_OVERFLOW = 1,
    CCTQUEUE_ERR_UNDERFLOW = 2,
    CCTQUEUE_ERR_TIMEOUT = 3
} CCTQueueError;


/************************************************************************/
/* Declare class and vtable.                        */
/************************************************************************/
struct CCThreadedQueue
{
    /* Super class must always be first member */
    /* of a class' struct. */
    struct CObject cobject;

    struct     
    {    
        struct CIQueue* backbone;

        /* Three OS objects are needed for thread safety.
         *      -> mutex
         *          Synchronize access to all backbone queue functions.
         *      -> insertBlock
         *          Provides a place for calling threads to block when they
         *          insert data, but the backbone is full.
         *      -> removeBlock
         *          Provides a place for calling threads to block when they
         *          read/remove data, but the backbone is empty.
         */
#ifdef __unix__
        pthread_cond_t insertCondition;
        pthread_cond_t removeCondition;
        pthread_mutex_t mutex;
#endif

    } _;
};

struct CCThreadedQueue_VTable
{
    /* Space for a copy of the super class' virtual table must  */
    /* be the first member of a class virtual table declaration. */
    struct CObject_VTable  cobject_override;

    /* Since we are overriding the destructor, we need to keep */
    /* keep a reference to the super class' implementation of */
    /* the destructor. */
    const struct CObject_VTable* cobject;
};

const struct CCThreadedQueue_VTable* CCThreadedQueue_VTable_Key( );


/************************************************************************/
/* Constructor                                                          */
/************************************************************************/
CError CCThreadedQueue( struct CCThreadedQueue* self, struct CIQueue* backbone );


/************************************************************************/
/* Class methods.                           */
/************************************************************************/
CCTQueueError CCThreadedQueue_Insert( struct CCThreadedQueue* self, const void* element, COS_Timemsec blockTime );

CCTQueueError CCThreadedQueue_Remove( struct CCThreadedQueue* self, void* element, COS_Timemsec blockTime );

CCTQueueError CCThreadedQueue_Peek( struct CCThreadedQueue* self, void* element, COS_Timemsec blockTime );

size_t CCThreadedQueue_Size( struct CCThreadedQueue* self );

size_t CCThreadedQueue_MaxSize( struct CCThreadedQueue* self );

/*
 * TODO: clear method should allow user to enter a clean up function.
 */
void CCThreadedQueue_Clear( struct CCThreadedQueue* self );


#endif /* UTIL_CCTHREADEDQUEUE_H_ */