What is PJLIB

PJLIB is an Open Source, small footprint framework library written in C for making scalable applications. Because of its small footprint, it can be used in embedded applications (we hope so!), but yet the library is also aimed for facilitating the creation of high performance protocol stacks.

PJLIB is released under GPL terms.

Download

PJLIB and all documentation can be downloaded from http://www.pjsip.org.

About This Documentation

This document is generated directly from PJLIB source file using doxygen (http://www.doxygen.org). Doxygen is a great (and free!) tools for generating such documentation.

How to Read This Document

This documentation is laid out more to be a reference guide instead of tutorial, therefore first time users may find it difficult to grasp PJLIB by reading this document alone.

However, we've tried our best to make this document easy to follow. For first time users, we would suggest that you follow these steps when reading this documentation:

continue reading this introduction chapter. At the end of this chapter, you'll find section called Principles in Using PJLIB which should guide you to understand basic things about PJLIB.
find information about specific features that you want to use in PJLIB. Use the Module Index to find out about all features in PJLIB (if you're browsing the HTML documentation, click on the Module link on top of the page, or if you're reading the PDF documentation, click on Module Documentation on the navigation pane on the left).

How To's

Please find below links to specific tasks that you probably want to do:

How to Build PJLIB
Please refer to Building, and Installing PJLIB page for more information.
How to Use PJLIB in My Application
Please refer to Configuring Application to use PJLIB for more information.
How to Port PJLIB
Please refer to Porting PJLIB page.
Where to Read Samples Documentation
Most of the modules provide link to the corresponding sample file. Alternatively, to get the list of all examples, you can click on Related Pages on the top of HTML document or on PJLIB Page Documentation on navigation pane of your PDF reader.
How to Submit Code to PJLIB Project
Please read Coding Convention before submitting your code. Send your code as patch against current Subversion tree to the appropriate mailing list.

Features

It's Open Source!

PJLIB is currently released on GPL license, but other arrangements can be made with the author.

Extreme Portability

PJLIB is designed to be extremely portable. It can run on any kind of processors (16-bit, 32-bit, or 64-bit, big or little endian, single or multi-processors) and operating systems. Floating point or no floating point. Multi-threading or not. It can even run in environment where no ANSI LIBC is available.

Currently PJLIB is known to run on these platforms:

Win32/x86 (Win95/98/ME, NT/2000/XP/2003, mingw).
arm, WinCE and Windows Mobile.
Linux/x86, (user mode and as kernel module(!)).
Linux/alpha
Solaris/ultra.
MacOS X/powerpc
RTEMS (x86 and powerpc).

And efforts is under way to port PJLIB on:

Symbian OS

Small in Size

One of the primary objectives is to have library that is small in size for typical embedded applications. As a rough guidance, we aim to keep the library size below 100KB for it to be considered as small. As the result, most of the functionalities in the library can be tailored to meet the requirements; user can enable/disable specific functionalities to get the desired size/performance/functionality balance.

For more info, please see Build Configuration.

Big in Performance

Almost everything in PJLIB is designed to achieve the highest possible performance out of the target platform.

No Dynamic Memory Allocations

The central idea of PJLIB is that for applications to run as fast as it can, it should not use malloc() at all, but instead should get the memory from a preallocated storage pool. There are few things that can be optimized with this approach:

alloc() is a O(1) operation.
no mutex is used inside alloc(). It is assumed that synchronization will be used in higher abstraction by application anyway.
no free() is required. All chunks will be deleted when the pool is destroyed.

The performance gained on some systems can be as high as 30x speed up against malloc() and free() on certain configurations, but of course your mileage may vary.

For more information, see Fast Memory Pool

Operating System Abstraction

PJLIB has abstractions for features that are normally not portable across operating systems:

Threads
Portable thread manipulation.
Thread Local Storage.
Storing data in thread's private data.
Mutexes.
Mutual exclusion protection.
Semaphores.
Semaphores.
Atomic Variables
Atomic variables and their operations.
Critical sections.
Fast locking of critical sections.
Lock Objects
High level abstraction for lock objects.
Event Object.
Event object.
Time Data Type and Manipulation.
Portable time manipulation.
High Resolution Timestamp
High resolution time value.
etc.

Low-Level Network I/O

PJLIB has very portable abstraction and fairly complete set of API for doing network I/O communications. At the lowest level, PJLIB provides:

Socket Abstraction
A highly portable socket abstraction, runs on all kind of network APIs such as standard BSD socket, Windows socket, Linux kernel socket, PalmOS networking API, etc.
Network Address Resolution
Portable address resolution, which implements pj_gethostbyname().
Socket select() API.
A portable select() like API (pj_sock_select()) which can be implemented with various back-end.

Timer Management

A passive framework for managing timer, see Timer Heap Management. for more info. There is also function to retrieve high resolution timestamp from the system (see High Resolution Timestamp).

Various Data Structures

Various data structures are provided in the library:

Exception Construct

A convenient TRY/CATCH like construct to propagate errors, which by default are used by the memory pool and the lexical scanner in pjlib-util. The exception construct can be used to write programs like below:

    #define SYNTAX_ERROR  1

    PJ_TRY {
       msg = NULL;
       msg = parse_msg(buf, len);
    }
    PJ_CATCH ( SYNTAX_ERROR ) {
       .. handle error ..
    }
    PJ_END;

Please see Exception Handling for more information.

Logging Facility

PJLIB Logging Facility consists of macros to write logging information to some output device. Some of the features of the logging facility:

the verbosity can be fine-tuned both at compile time (to control the library size) or run-time (to control the verbosity of the information).
output device is configurable (e.g. stdout, printk, file, etc.)
log decoration is configurable.

See Logging Facility for more information.

Random and GUID Generation

PJLIB provides facility to create random string (pj_create_random_string()) or globally unique identifier (see Globally Unique Identifier).

Configuring Application to use PJLIB

Building PJLIB

Follow the instructions in Building, and Installing PJLIB to build PJLIB.

Building Applications with PJLIB

Use the following settings when building applications with PJLIB.

Include Search Path

Add this to your include search path ($PJLIB is PJLIB root directory):

   $PJLIB/include

Include PJLIB Header

To include all PJLIB headers:

  #include <pjlib.h>

Alternatively, you can include individual PJLIB headers like this:

   #include <pj/log.h>
   #include <pj/os.h>

Library Path

Add this to your library search path:

   $PJLIB/lib

Then add the appropriate PJLIB library to your link specification. For example, you would add libpj-i386-linux-gcc.a when you're building applications in Linux.

Principles in Using PJLIB

Few things that you MUST do when using PJLIB, to make sure that you create trully portable applications.

Call pj_init()

Before you do anything else, call pj_init(). This would make sure that PJLIB system is properly set up.

Do NOT Use ANSI C

Contrary to popular teaching, ANSI C (and LIBC) is not the most portable library in the world, nor it's the most ubiquitous. For example, LIBC is not available in Linux kernel. Also normally LIBC will be excluded from compilation of RTOSes to reduce size.

So for maximum portability, do NOT use ANSI C. Do not even try to include any other header files outside <include/pj>. Stick with the functionalities provided by PJLIB.

Use pj_str_t instead of C Strings

PJLIB uses pj_str_t instead of normal C strings. You SHOULD follow this convention too. Remember, ANSI string-h is not always available. And PJLIB string is faster!

Use Pool for Memory Allocations

You MUST NOT use malloc() or any other memory allocation functions. Use PJLIB Fast Memory Pool instead! It's faster and most portable.

Use Logging for Text Display

DO NOT use <stdio.h> for text output. Use PJLIB Logging Facility instead.

Porting PJLIB

Please see Porting PJLIB page on more information to port PJLIB to new target.

Enjoy Using PJLIB!

We hope that you find PJLIB usefull for your application. If you have any questions, suggestions, critics, bug fixes, or anything else, we would be happy to hear it.

Enjoy using PJLIB!

Benny Prijono < bennylp at pjsip dot org >