dmmlib/private-include/block_header.h

/*
 *   Copyright 2011 Institute of Communication and Computer Systems (ICCS) 
 *
 *   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.
 *
 */

/**
 * \file 	block_header.h
 * \author 	Ioannis Koutras (joko@microlab.ntua.gr)
 * \date 	September, 2011
 *  
 * \brief Block header structure and functions, and memory block functions.
 */

#ifndef BLOCK_HEADER_H
#define BLOCK_HEADER_H

#include <stddef.h>
#include <stdbool.h>
#include <dmmlib/heap.h>

/** The header structure of every memory block inside a heap. */
typedef struct block_header_s {
	size_t size; /**< The LSB represents the availability of the block (1
		       for used, 0 for free), the rest the size of the data
		       part. */
	size_t requested_size; /**< The requested size of the data part */
	size_t previous_size; /**< The LSB represents the availability of the
				previous block, the rest the size of the data
				part of the previous block in the memory space */
	void *next; /**< The next memory block in the list that the current
		      block belongs to */
#ifdef WITH_OWNERSHIP
	heap_t *heap_owner; /** < A pointer to the heap the current block belongs to */
#endif /* WITH_OWNERSHIP */
} block_header_t;

/**
 * The size of the header in number of bytes
 */
#define HEADER_SIZE sizeof(block_header_t)

/**
 * Get the next memory block.
 *
 * \param ptr The pointer to the data part of the current memory block.
 *
 * \return The pointer of the data part of the next (in list) memory block.
 * \retval NULL There is no next memory block in the list.
 */
void * get_next(void *ptr);

/**
 * Get the size of the memory block's data
 *
 * \param ptr The pointer to the data part of the current memory block.
 *
 * \return The size of the data part of the current memory block.
 */
size_t get_size(void *ptr);

/**
 * Get the requested size of the memory block's data
 *
 * \param ptr The pointer to the data part of the current memory block.
 *
 * \return The size of the data that was initialy requested for this memory
 * block.
 */
size_t get_requested_size(void *ptr);

/**
 * Get all information of the memory block header's size record
 *
 * \param ptr The pointer to the data part of the current memory block.
 *
 * \return The availability and the size of the data part of the current memory
 * block.
 */
size_t get_size_availability(void *ptr);

/**
 * Set the size of the memory block's data
 *
 * \param ptr 	The pointer to the data part of the current memory block.
 * \param size 	The size of the data part of the current memory block.
 */
void set_size(void *ptr, size_t size);

/**
 * Set the requested size of memory block's data
 *
 * \param ptr 	The pointer to the data part of the current memory block.
 * \param size 	The requested size for the data part of the current memory
 * block.
 */
void set_requested_size(void *ptr, size_t size);

/**
 * Mark the memory block as used
 *
 * \param ptr 	The pointer to the data part of the memory block.
 */
void mark_used(void *ptr);

/**
 * Mark the memory block as free
 *
 * \param ptr 	The pointer to the data part of the memory block.
 */
void mark_free(void *ptr);

/**
 * Set the availability and the size of the previous memory block
 *
 * \param ptr 		The pointer to the data part of the previous memory block.
 * \param previous_size_availability The size for the data part of the previous
 * memory block on data layout level.
 */
void set_previous_size_availability(void *ptr, size_t previous_size_availability);

/**
 * Set the next memory block of a block
 *
 * \param block 	The pointer to the data part of the current memory
 * block.
 * \param next_block 	The pointer to the data part of the next memory block.
 */
void set_next(void *block, void *next_block);

#ifdef WITH_OWNERSHIP

/**
 * Set the heap owner of a memory block
 *
 * \param ptr 		The pointer to the data part of the memory block.
 * \param heap_owner 	The pointer to the heap owner.
 */
void set_owner(void *ptr, heap_t *heap_owner);

/**
 * Get the heap owner of a memory block
 *
 * \param ptr 	The pointer to the data part of the memory block.
 * \return 	The pointer to the heap owner.
 */
heap_t * get_owner(void *ptr);

#endif /* WITH_OWNERSHIP */

/**
 * Check if previous block (in the memory space) belongs to a free list
 */
bool is_previous_free(void *ptr);

/**
 * Get the size of the previous block (in the memory space) 
 *
 * \param ptr 	The pointer to the data part of the current memory block.
 */
size_t get_previous_size(void *ptr);

/**
 * Get the size and the availability of the previous block (in the memory
 * space) 
 *
 * \param ptr 	The pointer to the data part of the previous memory block.
 */
size_t get_previous_size_availability(void *ptr);

/**
 * Get the previous memory block (in the memory space)
 *
 * \param ptr 	The pointer to the data part of the current memory block.
 */
void * get_previous(void *ptr);

/**
 * Removes a memory block from a singly linked list of memory blocks.
 *
 * \param *block The block to be removed.
 * \param *starting_node The starting memory block of the list.
 */
void remove_block(void *block, void *starting_node);

#endif /* BLOCK_HEADER_H */