Home --> Documentations --> PJLIB Reference

Welcome to PJLIB!

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:

How To's

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

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:

And efforts is under way to port PJLIB on:

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:

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:

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:

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:

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 >

 


PJLIB Open Source, high performance, small footprint, and very very portable framework
Copyright (C) 2006-2009 Teluu Inc.