exceptions4c   version 3.0
An exception handling framework for C
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
e4c_rsc.h File Reference

exceptions4c automatic resource handling header file More...

#include "e4c.h"

Macros

Convenience macros for acquiring and disposing resources

These macros let you acquire and dispose different kinds of resources according to the dispose pattern.

#define e4c_using_memory(buffer, bytes)
 Introduces a block of code with automatic acquisition and disposal of a memory buffer. More...
 
#define e4c_using_file(file, path, mode)
 Introduces a block of code with automatic acquisition and disposal of a file stream. More...
 
#define e4c_using_mutex(mutex)
 Introduces a block of code with automatic acquisition and disposal of a mutex. More...
 

Variables

Resource handling exceptions
const e4c_exception_type MemoryAllocationException
 This exception is thrown when malloc returns a null pointer. More...
 
const e4c_exception_type FileException
 This exception is thrown when a file error occurs. More...
 
const e4c_exception_type FileOpenException
 This exception is thrown when a file cannot be opened. More...
 
const e4c_exception_type FileCloseException
 This exception is thrown when a file cannot be closed. More...
 
const e4c_exception_type MutexException
 This exception is thrown when a mutex error occurs. More...
 
const e4c_exception_type MutexLockException
 This exception is thrown when a mutex cannot be locked. More...
 
const e4c_exception_type MutexUnlockException
 This exception is thrown when a mutex cannot be unlocked. More...
 

Detailed Description

exceptions4c automatic resource handling header file

Version
2.0
Author
Copyright (c) 2012 Guillermo Calvo

exceptions4c automatic resource handling header file

This header file needs to be included in order to be able to use any of the automatic resource handling macros:

License

This is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this software. If not, see http://www.gnu.org/licenses/.

Macro Definition Documentation

#define e4c_using_file (   file,
  path,
  mode 
)
Value:
E4C_WITH(file, e4c_dispose_file){ \
file = e4c_acquire_file(path, mode); \
if(file == NULL){ \
E4C_THROW(FileOpenException, "Could not open file: " #path); \
} \
}E4C_USE

Introduces a block of code with automatic acquisition and disposal of a file stream.

Parameters
fileThe file to be acquired, used and then disposed
pathThe path of the file to be opened
modeThe access mode for the file

This macro lets you acquire and dispose (open and close) files according to the dispose pattern:

FILE * file;
e4c_using_file(file, "log.txt", "a"){
// implicit: file = fopen("log.txt", "a");
fputs("hello, world!\n", file);
// implicit: fclose(file);
}
Exceptions
FileOpenExceptionIf fopen returns NULL
FileCloseExceptionIf fclose does not return zero
#define e4c_using_memory (   buffer,
  bytes 
)
Value:
E4C_WITH(buffer, e4c_dispose_memory){ \
buffer = e4c_acquire_memory(bytes); \
if(buffer == NULL){ \
E4C_THROW(MemoryAllocationException, \
"Could not allocate memory for: " #buffer); \
} \
}E4C_USE

Introduces a block of code with automatic acquisition and disposal of a memory buffer.

Parameters
bufferThe buffer to be acquired, used and then disposed
bytesThe amount of memory to be allocated (in bytes)

This macro lets you acquire and dispose memory buffers according to the dispose pattern:

void * buffer;
e4c_using_memory(buffer, 1024){
// implicit: buffer = malloc(1024);
memset(buffer, 0, 1024);
// implicit: free(buffer);
}
Exceptions
MemoryAllocationExceptionIf malloc returns NULL
#define e4c_using_mutex (   mutex)
Value:
E4C_WITH(mutex, e4c_dispose_mutex){ \
int result = e4c_acquire_mutex(mutex); \
if(result != 0){ \
E4C_THROW(MutexLockException, "Could not lock mutex: " #mutex); \
} \
}E4C_USE

Introduces a block of code with automatic acquisition and disposal of a mutex.

Parameters
mutexThe mutex to be locked, used and then unlocked

This macro lets you lock and unlock mutexes according to the dispose pattern:

pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
int counter = 0;
// implicit: pthread_mutex_lock(&mutex);
counter++;
// implicit: pthread_mutex_unlock(&mutex);
}
Exceptions
MutexLockExceptionIf pthread_mutex_lock does not return zero
MutexUnlockExceptionIf pthread_mutex_unlock does not return zero

Variable Documentation

const e4c_exception_type FileCloseException

This exception is thrown when a file cannot be closed.

FileCloseException is thrown by e4c_using_file when fclose does not return zero for whatever reason.

Extends:
FileException
const e4c_exception_type FileException

This exception is thrown when a file error occurs.

FileException is the general type of exceptions produced by failed file operations.

Note
The specific cause of the error can be determined by checking the error_number of the exception; it captures the value of errno at the time the exception was thrown (i. e. right after fopen or fclose).
Extends:
InputOutputException
const e4c_exception_type FileOpenException

This exception is thrown when a file cannot be opened.

FileOpenException is thrown by e4c_using_file when fopen returns NULL for whatever reason.

Extends:
FileException
const e4c_exception_type MemoryAllocationException

This exception is thrown when malloc returns a null pointer.

MemoryAllocationException is thrown by e4c_using_memory when malloc returns NULL for whatever reason.

Extends:
NotEnoughMemoryException
const e4c_exception_type MutexException

This exception is thrown when a mutex error occurs.

MutexException is the general type of exceptions produced by failed mutex operations.

Extends:
RuntimeException
const e4c_exception_type MutexLockException

This exception is thrown when a mutex cannot be locked.

MutexLockException is thrown by e4c_using_mutex when fopen returns NULL for whatever reason.

Extends:
MutexException
const e4c_exception_type MutexUnlockException

This exception is thrown when a mutex cannot be unlocked.

MutexUnlockException is thrown by e4c_using_mutex when fclose does not return zero for whatever reason.

Extends:
MutexException