TweetFollow Us on Twitter

Shared Libraries in CPX
Volume Number:12
Issue Number:8
Column Tag:Programming Workshop

Using Shared Libraries in CPX

Can you really use the Code Fragment Manager and not go crazy?

By John Shackelford

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

Introduction

The Power Mac and upgrades to System 7 harbor many exciting new technologies waiting for application developers to explore. One new technology allows executable code to be shared at run-time. This means you can share code libraries across applications regardless of which development environment you use - or in other words you can finally start using all that code those C++ developers are writing down the hall from you! This technology is provided by a new manager called the Code Fragment Manager (CFM). The CFM is responsible for loading fragments, blocks of executable PowerPC code and data, into memory, and preparing them for execution. Currently the CFM is supported only on Power Macs. However, very soon the CFM will be supported on 68K Macs.

This article describes and demonstrates with some example code one approach to accessing shared libraries from Prograph CPX. It shows a way to wrap a C/C++ library, defining an XPrim that provides the interface to shared libraries and describing in detail a set of CPX classes which encapsulate the use of shared libraries. You’ll receive many benefits from using shared libraries in your applications, including reduced development time (because non-Prograph code no longer has to be ported to the Prograph language) and increased application speed (because of the native Power Mac code). The code described in this article gives you the basic tools for accessing shared libraries, listing export symbols, connecting to shared libraries, and executing functions. The code is shareware, and can be found at Tangent Systems’ Web page.

Figure 1. The main window for the demo app

Shared Library Demo Application

For this article I have created a simple demo application and two shared libraries. The demo application will access the shared libraries. The libraries each contain a different implementation of the same set of functions. One library (OOSharedLib) implements a set of functions using C++ code, while the other library (ExampleCLib) uses all C code.

When the application launches and opens its main window (Figure 1), it also “opens” or “connects to” the two shared libraries. The exported symbols or functions contained in each library are then available for the application to use. The functions or symbols that a library exports are listed in the main window. The functions in each library have been designed to operate on an array of data, and can compute the maximum, minimum, average, variance, or sum of the data.

You can select the desired library by choosing its name in the pop-up menu. The scroll list on the left side of the window lists the exported symbols of the selected shared library. When a symbol is selected in this scrolling list, the Do Function button becomes active. When the Do Function button is pushed, the selected function in the selected library is executed. The results are then listed in the right-hand scroll list.

The pop-up menu in the window lists the two shared libraries the application will work with. These libraries are loaded when the main window opens by a call to the window’s method /loadLibraries (Figure 2). A «Shared Library» instance is created for each shared library and stored in an attribute of the main window for later use.

Figure 2. Test Window has a method which loads
a list of shared libraries

Exported symbols are the items which can be referenced by other code fragments. You can think of exported symbols as the public functions the library supports. Internally there may be a lot of functions that are hidden from the outside world. This provides some measure of control over how the library is used - which can be a nice feature for developers and users. As a developer, I may not always want every function in the library to be exposed, for fear they might not be properly used; and as a user, I may not want to know all the gory details of someone else’s library. The typical Power Mac development environment has a procedure you must follow to define the export symbols. In CodeWarrior, for instance, there is a file (*.exp) you can edit prior to building the shared library, that controls which symbols will be exported (more on this later on).

Now let’s try one function with the demo; then we will dive into more Prograph code. With the application still running, select a function in the function list and click Do Function (or simply double-click a function in the function list).

The demo application on the CPX side of things generates a list of 50 numbers. It then sends this list (embedded in a data structure) as an argument to the chosen function in the shared library. The shared library function then calculates the result and sends it back to the application (Figure 3). For the case where we use OOSharedLib and its get_average function, I did some timing analysis and found that a pure Prograph-coded equivalent using CPX built-in list primitives can be slower (I compared 68K compiled CPX to using a PPC-native shared library). Using 8000 values on a Power Mac 7100/80 (System 7.5), I got these results:

Interpreted CPX 200 Ticks

Compiled CPX 20 Ticks

Using native shared library < 1 Tick

(By the way, in looking at my Prograph code, don’t be put off by the idiosyncracies of my shorthand comments to myself, where I’m reminding myself what data type is being input or output. “<Shared Library>” means «Shared Library», an instance of the Shared Library class; at the time I was writing that comment I didn’t know how to type the '«' character! Use of parentheses generally indicates a list; so, for instance, “():name” means “a list of names”.)

Figure 3. The method /doFunction handles the execution of the selected library function

The local setup data_cache builds up a vector of data in a data structure to be sent off to the shared library. Figure 4 shows the fields of this structure. The functions in the shared library have been designed to return the result in the result field.

Figure 4. The data_cache fields
as shown in the CPX “info” window

SLD Kit CPX interface

On the CPX side of the things, the interface for using shared libraries is handled by a class called Shared Library. For Power Mac-native shared libraries you’ll actually use its subclass Shared Library PPC. When the port to 68K machines is complete, CPX users will use the Shared Library 68K subclass. The purpose of the Shared Library class is to encapsulate all the low-level calls to the CFM and the Mixed Mode Manager when working with shared libraries. The class provides a set of methods to access shared libraries. We will now review the six most significant of these methods.

Figure 5. /getLibrary gets a Connection ID to the shared library

/getLibrary

This method (Figure 5) retrieves a connection identification number using the toolbox call GetSharedLibrary. That call is in the local get shared library. The attribute Connection ID comes into play when using functions in the shared library or listing the exported symbols.

/closeLibrary

This method uses the Connection ID to close the connection (Figure 6).

Figure 6. /closeLibrary closes the connection to the shared library

/executeFunction

This method calls the function in the shared library (Figure 7). Two Shared Library methods are called prior to the final call to the shared library function via the XPrim exec-code-frag. The method /getGlue gets a chunk of embedded code (Shackelford [1994]) that exec-code-frag needs. The method /findSymbol gets a pointer to the function in the shared library. The XPrim exec-code-frag makes the call to the selected function.

Figure 7. /executeFunction encapsulates low-level CFM calls

Figure 8. /listSymbols obtains a list of function pointers

Figure 9. /listSymbolInfos gets basic information for symbols exported by a shared library

Figure 10. /findSymbol gets the function pointer
for a specific symbol by name

/listSymbols

This method can be used to get pointers to the functions exported by the shared library (Figure 8).

/listSymbolInfos

This method can be used to get pointers to the functions exported by the shared library, names of the functions, and SymClass for each function (Figure 9).

/findSymbol

This method can be used to get a specific function pointer. You must pass in the name of the function (Figure 10).

C++ Wrapper

For this article I created a small C++ library. I’ll show a function in that library and the wrapper code that was written to access it from CPX. The wrapper technique is basically the same for each function. I won’t discuss the pure C library (ExampleCLib), since the C++ version is more general as concerns the techniques required to access shared libraries from CPX. The C++ code is a simple class called Tvector. It provides a way to do calculations on a single-dimensional array of data. The next few listings show the declaration file for the shared library (OOSharedLib), the declaration file for the data structure we use to pass data into the shared libraries from CPX, the declaration file for the wrapper functions, the declaration file for the Tvector class, and the implementation files for the wrapper functions and the Tvector class.

Listing 1: OOSharedLib.h
Declaration file for the OOP shared library for this article.

#ifndef OOSHAREDLIB_H
#define OOSHAREDLIB_H
/*
    OOSharedLib.h
    
    Purpose: Header file for OOSharedLib.c
    
    This is the public function interface.
*/

#include "OOSharedLibStructs.h"

#if defined(__cplusplus)
extern "C" {
#endif


void get_average(data_cache *data);
void get_maximum(data_cache *data);
void get_minimum(data_cache *data);
void get_sum(data_cache *data);
void get_variance(data_cache *data);

#if defined(__cplusplus)
}
#endif
#endif

Listing 2: TanLibStructs.h

Declaration file for the data_cache. This is in a separate file so that we can use it with Prograph C Tool to 
“expose” or define the data structures for CPX - i.e. we can allocate the structure and fill the fields.

#ifndef TAN_LIB_STRUCTS_H
#define TAN_LIB_STRUCTS_H
/*
    © 1995 Tangent Systems
    All Rights Reserved.
    
    Public declarations for interface structures.
    Putting these declarations in a separate header makes it easier when it
    comes time to use Prograph C Tool to define these strcutures for use in CPX.
*/

#pragma pgtype double Real8
#pragma pgtype int Int4
#pragma pgtype unsigned Nat4

typedef struct {
 unsigned long length;
 int  success;
 double result;
 double *data;
 } data_cache;
 
#endif

Listing 3: Tvector.h

Declaration file for Tvector class. Defines simple methods for doing calculations on one dimensional arrays 
of doubles. Each Tvector has an array of doubles.

#ifndef TVECTOR_H
#define TVECTOR_H

class Tvector
{
 public:
    // Attributes
 unsigned long length;  // Number of element in this object
 double *theVector;
 
    // Methods
 Tvector(unsigned long length, double *aVector);
 ~Tvector();

 int calc_average(double *result);
 int calc_maximum(double *result);
 int calc_minimum(double *result);
 int calc_sum(double *result);
 int calc_variance(double *result);
 
 protected:
 
 private:
 int ok_vector;
 
};

#endif

As you can see, the class provides a constructor, a destructor, and five “mathematical” methods. Let’s look at get_average, which wraps the method calc_average. One limitation we have is that on the CPX side we will be allowed only one argument when making a call. So each wrapper will be designed to provide one argument - a pointer to a structure. We will handle the allocation and deletion of Tvector objects as needed.

Listing 4: get_average

Wraps method “calc_average” in class Tvector. Uses the Tvector class to calculate the average value of 
an array of doubles buried in data_cache.

/*
Pass in a pointer to data_cache, calculates the average value and returns
the answer in data_cache->result.
*/
void get_average(data_cache *theData)
{
 Tvector* aVector;
 double average = 0;
 TestDebug;
 
 aVector = new Tvector(theData->length, theData->data);
 theData->success = aVector->calc_average(&average);

 theData->result = average;
 delete(aVector);
}

The C function get_average instantiates a Tvector (aVector), passing the data to it (a pointer to data_cache). It then sends the message calc_average to aVector. The function captures the result in a local variable called average. The value of average is then passed back in the data_cache structure. All the wrappers are written so that there is only one calling argument and it is a pointer to a data structure. Here are the Tvector methods used in the wrapper function get_average.

Listing 5: Tvector

Constructor, destructor and method “calc_average” for class Tvector. This is only a partial listing of the 
the file Tvector.c.

Tvector::Tvector(unsigned long theLength, double *aVector)
{
 int i;
 ok_vector = 0;
 if(theLength < 0)
 {
 length = 0;
 return;
 }
 theVector = new double[theLength];

 for(i = 0;i < theLength; i++)
 {
 theVector[i] = aVector[i];
 }

 length = theLength;
 ok_vector = 1;
}
 
Tvector::~Tvector()
{
 delete(theVector);
 ok_vector = 0;
}

int Tvector::calc_average(double *result)
{
 int i;
 double theResult = 0;
 *result = theResult;
 if(ok_vector == 1)
 {
 for(i=0; i<length; i++)
 {
 theResult += theVector[i];
 }
 theResult = theResult/i;
 }
 *result = theResult;
 return ok_vector;
}

Building Shared Libraries

I used CodeWarrior for this article, and now I’ll show the files you’ll need to create a shared library. In general there are some special files you’ll need to include in the project file, there are some preferences you’ll have to set for the project, and then there is an export definition file (the .exp file) that you’ll need to define. According to the CodeWarrior documentation, you’ll need the files listed below under “libraries” and “MW Sources” (Figure 11).

Figure 11. To build a shared library
there are a few required files

Figure 12. Define the name of the shared library
in the PEF preference panel

Figure 13. Define the creator and type attributes of the shared library in the Project preference panel

Before building the shared library there a few preferences you’ll need to set up. See the CodeWarrior documentation for a complete description of the steps. I’ll highlight a few items to get you started. You’ll have to define the name of the library or fragment. That is defined in the “PEF” portion of the preferences in CodeWarrior (Figure 12).

You’ll also define the type and creator attributes, and the fact that the project is going to build a shared library. This is accomplished in the “Project” preferences panel (Figure 13).

One of the final steps before building the shared library is to define the symbols to be exported. If the Project file does not find the appropriate .exp file, it will export all functions. You can control what functions are made publicly available by creating a file with the same name as the project file, plus the .exp extension. When compilation occurs, the exported symbols will be those functions listed in the .exp file. So, for example, the project file for the OOSharedLib is called OOSharedLib.µ. The export file for this project would be named OOSharedLib.µ.exp. Listing 6 shows the content of the file in order to export our functions.

Listing 6: Export file

The export file defines the symbols that are made available for external use.

get_average
get_maximum
get_minimum
get_sum
get_variance

Conclusion and Future Plans

With the information in this article, CPX developers can now start planning, designing, and experimenting with shared libraries on the Power Mac. This powerful new feature of the Mac OS offers exciting possibilities to CPX developers, and the code in this article provides a mechanism to unleash that power.

We view the SLD Kit as another tool for CPX developers to use. We are developing a suite of high-performance technically-oriented shared libraries. The first commercial shared library we are releasing for CPX developers will be a Wavelet packet library. The core of the library is written in C++ and currently runs on DOS, Windows and UNIX. A CPX class will be developed to encapsulate the calls to the shared library. The class will provide basic data compression and Wavelet packet analysis functions. Potential application areas for such a library include voice compression, speech recognition, and digital communications.

Bibliography and References

Shackelford, John H. “You Can Have Your ‘C’ and Call It Too!”, Visual News 15 (November 1994) 9-12.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

GarageSale 7.0.7 - Create outstanding eB...
GarageSale is a slick, full-featured client application for the eBay online auction system. Create and manage your auctions with ease. With GarageSale, you can create, edit, track, and manage... Read more
SpamSieve 2.9.28 - Robust spam filter fo...
SpamSieve is a robust spam filter for major email clients that uses powerful Bayesian spam filtering. SpamSieve understands what your spam looks like in order to block it all, but also learns what... Read more
Thunderbird 45.7.1 - Email client from M...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more
Opera 43.0.2442.991 - High-performance W...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more
OnyX 3.2.4 - Maintenance and optimizatio...
OnyX is a multifunction utility that you can use to verify the startup disk and the structure of its system files, to run miscellaneous maintenance and cleaning tasks, to configure parameters in the... Read more
VueScan 9.5.71 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Slack 2.5.1 - Collaborative communicatio...
Slack is a collaborative communication app that simplifies real-time messaging, archiving, and search for modern working teams. Version 2.5.1: New The way we load teams you don't view often has been... Read more
HandBrake 1.0.3 - Versatile video encode...
HandBrake is a tool for converting video from nearly any format to a selection of modern, widely supported codecs. Features Supported Sources VIDEO_TS folder, DVD image or real DVD (unencrypted... Read more
Vivaldi 1.7.735.46 - An advanced browser...
Vivaldi is a browser for our friends. In 1994, two programmers started working on a web browser. Our idea was to make a really fast browser, capable of running on limited hardware, keeping in mind... Read more
Vivaldi 1.7.735.46 - An advanced browser...
Vivaldi is a browser for our friends. In 1994, two programmers started working on a web browser. Our idea was to make a really fast browser, capable of running on limited hardware, keeping in mind... Read more

Last week on Pocket Gamer
If you’re wondering what’s going on in the wider world of portable gaming, our sister site PocketGamer has you covered. Each week we like to check in on the PG team and see what they’ve been preoccupied with. From the latest on the Nintendo Switch... | Read more »
Mudd Masher arrives this week
Atooi Games, the minds behind Totes the Goat and Mutant Mudds, have a new game in the works -- Mudd Masher. The game, a hybrid of the independent studio's first two titles, is expected to launch this week on March 2. [Read more] | Read more »
The best sales on the App Store this wee...
The App Store has quite an exciting lineup of discount games this week that range across a variety of genres. It's a great opportunity to catch up on some of the premium games you may have been holding off on -- and some you can even grab for free... | Read more »
The best new games we played this week
Ah, here we are again at the close of another busy week. Don't rest too easy, though. We had a lot of great new releases in mobile games this week, and now you're going to have to spend all weekend playing them. That shouldn't be too much of a... | Read more »
Rollercoaster Tycoon Touch Guide: How to...
| Read more »
Rabbids Crazy Rush Guide: How to unlock...
The Rabbids are back in a new endless running adventure, Rabbids Crazy Rush. It's more ridiculous cartoon craziness as you help the little furballs gather enough fuel (soda) to get to the moon. Sure, it's a silly idea, but everyone has dreams --... | Read more »
Tavern Guardians (Games)
Tavern Guardians 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Tavern Guardians is a Hack-and-Slash action game played in the style of a match-three. You can experience high pace action... | Read more »
Slay your way to glory in idle RPG Endle...
It’s a golden age for idle games on the mobile market, and those addictive little clickers have a new best friend. South Korean developer Ekkorr released Endless Frontier last year, and players have been idling away the hours in the company of its... | Read more »
Tiny Striker: World Football Guide - How...
| Read more »
Good news everyone! Futurama: Worlds of...
Futurama is finding a new home on mobile in TinyCo and Fox Interactive's new game, Futurama: Worlds of Tomorrow. They're really doing it up, bringing on board Futurama creator Matt Groening along with the original cast and writers. TinyCo wants... | Read more »

Price Scanner via MacPrices.net

13-inch 2.7GHz Retina MacBook Pro on sale for...
B&H Photo has the 2015 13″ 2.7GHz/128GB Retina Apple MacBook Pro on sale for $150 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro (MF839LL/A): $... Read more
13-inch 1.6GHz/256GB MacBook Air on sale for...
Newegg has the 13″ 1.6GHz/256GB MacBook Air (MMGG2LL/A) on sale for $1029.99 including free shipping. Their price is $170 off MSRP, and it’s the lowest price available for this model. Choose Newegg... Read more
Apple refurbished Apple TVs available for up...
Apple has Certified Refurbished 32GB and 64GB Apple TVs available for up to $30 off the cost of new models. Apple’s standard one-year warranty is included with each model, and shipping is free: -... Read more
27-inch 3.3GHz 5K iMac on sale for $2099, sav...
B&H Photo has the 27″ 3.3GHz 5K Apple iMac on sale for $2099.99 including free shipping plus NY sales tax only. Their price is $200 off MSRP. Amazon also has the 27″ 3.3GHz 5K iMac on sale for $... Read more
21-inch iMacs on sale for up to $111 off MSRP
B&H Photo has select 21″ Apple iMacs on sale for up to $110 off MSRP, each including free shipping plus NY sales tax only: - 21″ 2.8GHz iMac: $1189 $110 off MSRP - 21″ 1.6GHz iMac: $999 $100 off... Read more
12-inch 1.2GHz Retina MacBooks on sale for $2...
Newegg has the 12″ 1.2GHz Space Gray Retina MacBook (sku MLH82LL/A) on sale for $1349.99 including free shipping. Their price is $250 off MSRP, and it’s the lowest price available for this model.... Read more
13-inch MacBook Airs on sale for $100 off MSR...
B&H Photo has 13″ MacBook Airs on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/128GB MacBook Air (MMGF2LL/A): $899 $100 off MSRP - 13″ 1.6GHz/... Read more
9-inch 32GB Silver iPad Pro on sale for $549,...
B&H Photo has the 9.7″ 32GB Silver Apple iPad Pro on sale for $549 for a limited time. Shipping is free, and B&H charges NY sales tax only. Their price is $50 off standard MSRP for this model... Read more
13-inch 2.0GHz Apple MacBook Pros on sale for...
B&H has the non-Touch Bar 13″ 2.0GHz MacBook Pros in stock today and on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.0GHz MacBook Pro Space Gray (... Read more
15-inch Touch Bar MacBook Pros on sale for up...
B&H Photo has the new 2016 15″ Apple Touch Bar MacBook Pros in stock today and on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more

Jobs Board

*Apple* Solutions Consultant - Apple (United...
# Apple Solutions Consultant Job Number: 55676865 Los Angeles, California, United States Posted: Feb. 22, 2017 Weekly Hours: 40.00 **Job Summary** As an Apple Read more
Programmer/Editor *Apple* Music Dance - App...
# Programmer/Editor Apple Music Dance Job Number: 55565967 Culver City, California, United States Posted: Feb. 23, 2017 Weekly Hours: **Job Summary** Apple Music Read more
Digital Marketing Specialist - *Apple* iClo...
# Digital Marketing Specialist - Apple iCloud Job Number: 54729233 Culver City, California, United States Posted: Feb. 22, 2017 Weekly Hours: 40.00 **Job Summary** Read more
Marketing Specialist, iTunes & *Apple*...
# Marketing Specialist, iTunes & Apple Music Job Number: 55704205 Culver City, California, United States Posted: Feb. 23, 2017 Weekly Hours: 40.00 **Job Summary** Read more
*Apple* Wireless Lead - T-ROC - The Retail O...
…of knowledge in wireless sales and activations to the Beautiful and NEW APPLE Experiencestore within MACYS. THIS role, APPLE Wireless Lead, isbrandnewas MACYS Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.