Introduction
The standard C library actually contains deficiencies in scope, simply because it has not been updated to reflect modern programming needs. For example, while it does encapsulate standard operating services such as disk and terminal IO, it does not capture operating system services such as threads, and timers. It also does not provide a standard set of container data structures, like linked lists and hash tables. Additionally, various operating systems sometimes differ in their support for these newer services; to support multiple operating systems a compatibility layer must be written. Finally, certain operating system services are not sufficient for modern use or not sufficient for use within a clustered environment — for example, the standard Unix timer allows only a single timer per process (we allow thousands), and the logging service has only minimal cluster support (we provide a fully cluster-aware logging system).
Overview
The Basic Infrastructure provides libraries that supply additional functionality, address insufficient APIs, and provide a compatibility layer. Additionally, the Basic Infrastructure handles the operational details of running within the OpenClovis distributed computing environment. These essential services, memory and data management are used by all the OpenClovis software and utilities. Customer applications are also welcome to use these APIs to take advantage of this infrastructure.
Components of Basic Infrastructure
Basic Services
Execution Object (EO)
SAFplus applications must interact with other aspects of the SAFplus infrastructure, by issuing RPC calls, receiving AMF requests, events etc. So each application essentially must be a multi-threaded client/server in order to interact with SAFplus, irrespective of whether your “main” is single-threaded. This functionality is encapsulated within the EO library, is activated when any SAFplus library is first initialized, and is normally almost completely hidden from the application
code.
The EO library creates a task pool per IOC (communications channel) priority per EO. The task pool is attached to a job queue and is configured in code to have a maximum number of servicing threads.
Log Service
Logging plays an important role in any software. Log provides information about how software works, what the current workflow is… By reading the logs, developers can diagnose the root cause for a problem.
OpenClovis SAFplus has 2 preconfigured log streams: app log and sys log. App log is from the
application and sys log is from the core components like amf, gms, ckpt…
There are 3 logging types:
- ASCII logging: there are two ways application can do ASCII logging. The first method is
by calling clLogWriteAsync() with msgId field as CL_LOG_MSGID_PRINTF_FMT, the second way is by calling clAppLog() macro.
- Binary logging: should be done through clLogWriteAsync() API with msgId field as CL_LOG_MSGID_BUFFER.
- TLV (Tag Length Value) logging: should be done through clLogWriteAsync() API with user defined msgIds other than CL_LOG_MSGID_BUFFER and
CL_LOG_MSGID_PRINTF_FMT
Log severities:
- EMERGENCY: system is unusable
- ALERT: action must be taken immediately
- CRITICAL: critical conditions
- ERROR: error conditions
- WARN: warning conditions
- NOTICE: normal but significant condition
- INFO: informational messages
- DEBUG: debug-level messages
- TRACE: Information about entering and leaving functions and libraries.
Example to open a log stream:
// init stream attributes:
ClUint32T length = 0;
ClCharT* pAppName=”your app name”;
ClLogStreamAttributesT pStreamAttr;
length = FILESUFFIX_LEN + strlen(pAppName) + 1;
pStreamAttr.fileName = clHeapAllocate(length);
if( pStreamAttr.fileName )
{
snprintf(pStreamAttr.fileName, length, “%s%s”, pAppName, FILESUFFIX);
}
length = strlen(FILELOCATION) + 1;
pStreamAttr.fileLocation = clHeapAllocate(length);
if( pStreamAttr.fileLocation )
{
snprintf(pStreamAttr.fileLocation, length, “%s”, FILELOCATION);
}
pStreamAttr.fileUnitSize = 150000000L; /*150 MB */
pStreamAttr.recordSize = 300;
pStreamAttr.fileFullAction = CL_LOG_FILE_FULL_ACTION_ROTATE;
pStreamAttr.maxFilesRotated = 3;
pStreamAttr.flushFreq = 20;
pStreamAttr.flushInterval = 20000000;
ClLogStreamHandleT *pLogStream;
ClLogHandleT sInitHandle = CL_HANDLE_INVALID_VALUE;
//Init logging library
clLogInitialize(&sInitHandle, NULL, &version);
clLogStreamOpen(sInitHandle, streamName, CL_LOG_STREAM_LOCAL,
&pStreamAttributes, CL_LOG_STREAM_CREATE, 0, pLogStream);
// then write data to the opened log stream:
clLogWriteAsync(pLogStream,CL_LOG_SEV_DEBUG
CL_LOG_DEFAULT_SERVICE_ID,
CL_LOG_MSGID_PRINTF_FMT,
“Log string”);
Operating System Abstraction Layer (OSAL)
The OpenClovis Operating System Abstraction Layer (OSAL) provides a standard interface to
commonly used operating system functions. The OSAL layer supports target operating systems
like most varieties of Linux.
All OpenClovis SAFplus Platform components are developed based on OSAL that provides an
OS agnostic function to all system calls, such as process and thread management functions.
Internally, OSAL maps such functions to the respective equivalent system calls provided by the
underlying OS. This allows OpenClovis SAFplus Platform as well as all OpenClovis
SAFplus-based applications to be ported to new operating systems with no modifications
API examples:
// create a thread:
clOsalTaskCreateAttach()
// with mutex
clOsalMutexCreate()
clOsalMutextLock()
clOsalMutextUnlock()
//with process
clOsalProcessCreate()
…
Timer Library
The OpenClovis Timer Library enables you to create multiple timers to execute application specific functionality after certain intervals. It performs the following functions:
- Creates multiple timers.
- Specifies a time-out value for each timer.
- Creates one-shot or repetitive timers.
- Specifies an application specific function that should be executed every time the timer fires or expires.
API examples:
clTimerInitialize()
clTimerCreate()
clTimerStart()
clTimerStop()
…
SAFplus Platform Console
The OpenClovis SAFplus Platform Console is a simple command line interface (CLI) that provides diagnostic access to all system components (including OpenClovis SAFplus Platform service components, and eonized customer applications), irrespective of the location (node) where the component runs. This CLI is designed to assist the application developers and field engineers in testing and debugging applications, and so is also called the “Debug CLI”.
See the safplus_console article for more information.
Memory Management
This module includes data structures and wrapper classes for memory management
Containers
Supports three types of containers listed as follows:
- Doubly linked list
- Hashtable (supports open-hashing)
- Red-Black trees (balanced binary tree)
API examples:
clCntHashtblCreate()
clCntRbtreeCreate()
clCntNodeAddAndNodeGet()
…
Circular List
The OpenClovis Circular List provides implementation of circular linked list and supports addition, deletion, and retrieval of node and walks through the list.
API examples:
clClistCreate()
clClistFirstNodeAdd()
clClistNodeDelete()
…
Queue Library
The OpenClovis Queue Library provides implementation for an ordered list. It supports enqueuing, dequeuing, and retrieval of a node and walk through the queue.
API examples:
clQueueCreate()
clQueueNodeInsert
clQueueNodeDelete()
…
Buffer Management Library
The OpenClovis Buffer Manager Library is designed to provide an efficient method of user-space buffer and memory management to increase the performance of communication-intensive OpenClovis SAFplus Platform components and user applications. It contains elastic buffers that expand based on application memory requirement.
API examples:
clBufferCreate()
clBufferNBytesRead()
clBufferNBytesWrite()
Heap Management Library
Heap memory is used for dynamic memory allocation. Memory is allocated from a large pool of unused memory area called the heap. The size of the memory allocation can be determined at run-time. The OpenClovis heap memory subsystem allows the components to be configured with allocation limits so that a process with a memory leak will not consume resources needed by other processes. Additionally allocation alarms can be configured so that the operator can be notified of imminent memory exhaustion and appropriate action be taken.
API examples:
clHeapAllocate()
clHeapFree()
clHeapShrink()
…
Data Management
Database Abstraction Layer (DBAL)
The OpenClovis Database Abstraction Layer (DBAL) provides a standard interface for any OpenClovis SAFplus Platform infrastructure component or application to interface with databases. Supports:
- the SQLite database
- the GNU Database Manager (GDBM).
- the Oracle Berkeley DB
The primary user of this interface is the COR component which can write or read its object repository to and from a database for either persistent storage or offline processing. DBAL is also a standalone library with no dependencies on any other OpenClovis SAFplus Platform components.
Conclusion
OpenClovis Basic Infrastructure provides library APIs for developers to simplify their development by using wrappers of Operating System layers like threads, processes, mutexes, timer… data structure like linked list, queue, circular list, Red Black tree…, dynamic memory management like heap management,… Besides, developers can use logging service to track their workflows, debug information… so that they can diagnose a root cause for an issue from their programs.
Other support, please send email to support@openclovis.org.