Cosm Client-Server
Software Development Kit
Setup (before you code)
Server Functions
Client Functions
Read this first
Mithral's Cosm Client-Server Software Development Kit allows people
to quickly and easily write large scale client-server applications
including "distributed computing" and "GRID" applications.
Examples of what this will allow you to build with this technology are
distributed.net, SETI@Home, Napster, Gnutella, and hundreds of other
applications. The example code is an instance of an application
that hands out work for the clients to do, then collects the results.
The CS-SDK is a kit that should allow a first-year programmer
to take an application and make it into a client-server application
in a weekend. Naturally, if your application doesn't already
exist, than you have a few months of project design and development
ahead of you. Also, if your application was not written
to be portable, you will also have additional work to do integrating
the Cosm CPU/OS layer with your application.
The first thing you will have to do to use this kit is get familiar
with client-server architectures. If you're not familiar with
client-server models, find someone who is to help you with your
project. Your mistakes can cause untold headaches for network
adminitrators if you design your project incorrectly.
Next you will need to install the Cosm libraries, read the
Programmers Guide, license, and API documentation. These can all be
found on the Mithral web site. Read them. You will also need to be
familiar with the correct use of ANSI C. In general you should avoid
use of the C standard library, unsafe functions have been replaced with
functions in the Cosm API. Not following the documentation will
result in non-portable and error-prone applications. Reading all the
documentaiton and getting the libraries installed should take a few
hours.
After that reading, return to this document and finish reading it.
It will make little sense until you read the previously mentioned
documentation. Now go do the reading, which we all know you didn't
do yet ;) If you skipped even this "read this first" reading, then
eventually you'll be back looking for a reason your project doesn't
work.
The rest should be relatively straitforward, if not let us know.
Read this document, read the three .h and two .c files, `make` the
example and play with it. Look at how the code does what it does.
The example should run without changes since it's configured to run
on localhost.
Now you should be ready to rip out the example code, and put in
your own. Join us in the IRC channel #cosm on Open Projects Net IRC for
help and to chat with others working on projects - someone may just
be awake when you /join.
Structures
There are 5 structures in common.h that you need to know about and
modify for your project.
- PACKET_REQUEST
- A request from the client to the server for some work. The
only read data needed is the amount of work the client expects to do
in a day.
- PACKET_ASSIGNMENT
- Assignment from the server to the client containing all the data
needed to do a piece of work. Number ranges, raw data, etc.
- PACKET_RESULTS
- Results of the work, sent back to the server. Should contain the
results as well as who did the work and other data you need for
statistics.
- PACKET_ACCEPT
- Acknowledgement from the server that the work results were
recieved and saved. This allows the client to delete the work.
A simple PASS/FAIL is enough.
- PACKET_ACTIVE
- This isn't so much a packet, since it only exists on the client,
but it needs to be treated as such (endian issues etc.) when saved
to the CLIENT_DATAFILE. This contains the work assignments along
with any temporary data. Work may be in an unstarted, unfinished
(checkpointed), or finished state ready to go back to the server
when in this structure.
Filenames
Client files (client.h)
- CLIENT_DATAFILE
- File that temporary data and work data will be saved to.
- CLIENT_CONFIG
- Client configuration file.
- CLIENT_LOG
- File for client log.
Server files (server.h)
- SERVER_DATAFILE
- Datafile(s) that the server needs for assignment/work data.
- SERVER_CONFIG
- Server configuration data (optional).
- WORK_LOG
- Log of completed work, along with statistical data.
- ACTIVITY_LOG
- Log for other activity like network and debug information.
Logging
Client logging
On the client the CLIENT_LOG should include everything that
you would send to the screen. At lower log levels this may just
be the work being received and sent. At higher levels you may want
to include additional things like networking logs, or progress
indicators.
Server logging
For the server there are (at least) two logs. The WORK_LOG should
log work recieved as done, along with the time, user, and other data
needed for statistics processing. The ACTIVITY_LOG is for all other
logging, including network connections, startup/shutdown messages,
diagnostics, or other debug information.
Networking
You will need to change both NETPACKET_SERVER and NETPACKET_PORT in
common.h for the full hostname and port your server will run on.
Anything above port 1024 will work, but 10204 is recommended,
becasue nothing else is assigned in the 10200-10300 range.
NETPACKET_HTTPSERVER and NETPACKET_HTTPPORT also need to be sent
projects that will tunnel through HTTP. NETPACKET_HTTPPORT should
usually be 80 or 8080.
If you are going to use HTTP tunneling on port 80, you need
to first be sure your servers dont already have web servers running.
You may only want HTTP modes, or you can keep both, which will
preaty much get through any firewall.
Examples
The example code is part of the standard files. This was done because
most all of what you have to do to customize for your own project is
to simply replace what's done in the example. If you want a "clean"
version, just delete everything but the defines and function
declarations.
catch_signal
Syntax
void catch_signal( int arg );
Description
Sets __shutdown_flag to 1 on signal. In the example it shuts
down immediately, but with multi-connection or multi-thread versions
you may want to delay shutdown.
Return Values
None.
Errors
None.
Example
See server.c
Initialize
Syntax
s32 Initialize( cosm_NET * net );
Description
This function is responsible for loading in the unassigned work,
assigned work, and other state information needed for the server. It
also sets up the network listening port, and any other initial setup.
Return Values
COSM_PASS on success, or COSM_FAIL on failure.
Errors
None.
Example
See server.c
Shutdown
Syntax
s32 Shutdown( void );
Description
This function closes any network connections, and saves all the state
data such as unassigned work.
Return Values
COSM_PASS on success, or COSM_FAIL on failure.
Errors
None.
Example
See server.c
Assign
Syntax
void Assign( cosm_NET * net );
Description
This function takes the open network connection net and reads
the remainder of a PACKET_REQUEST packet, assigns the client
some work, tracks the assigned work, and then sends a
PACKET_ASSIGNMENT packet to the client with the assigned work.
Return Values
None.
Errors
None.
Example
See server.c
Accept
Syntax
void Accept( cosm_NET * net );
Description
This function takes the open network connection net and reads
the remainder of a PACKET_RESULTS packet, saves the completed
work, logs it, and then returns a PACKET_ACCEPT packet to the
client for acknowledgement.
Return Values
None.
Errors
None.
Example
See server.c
catch_signal
Syntax
void catch_signal( int arg );
Description
Sets __shutdown_flag to 1 on signal.
Return Values
None.
Errors
None.
Example
See client.c
Load
Syntax
u32 Load( void );
Description
Load in all the PACKET_ACTIVE's from SUSPEND_FILENAME.
Usually only done at startup.
Return Values
Number of PACKET_ACTIVE structures loaded.
Errors
None.
Example
See client.c
Save
Syntax
s32 Save( void );
Description
Save all the valid (active, done) PACKET_ACTIVE's to
SUSPEND_FILENAME. This is done both at shutdown and for
checkpointing.
Return Values
COSM_PASS on success, or COSM_FAIL on failure.
Errors
None.
Example
See client.c
GetWork
Syntax
u32 GetWork( PACKET_ACTIVE * work, u32 count );
Description
Connect to the server, request a days worth of work with a
PACKET_REQUEST packet, and read back the
PACKET_ASSIGNMENT packet, storing the assigned work locally.
If a given work is already loaded, it will not overwrite it.
Return Values
Number of PACKET_ACTIVE's received.
Errors
None.
Example
See client.c
PutWork
Syntax
u32 PutWork( PACKET_ACTIVE * work, u32 count );
Description
Connect to the server, send in a PACKET_RESULTS packet, and
expect back a PACKET_ACCEPT packet. Once the work is
acknowledged, it can be deleted. Will only send work that
is done.
Return Values
Number of PACKET_ACTIVE's sent in.
Errors
None.
Example
See client.c
Connect
Syntax
s32 Connect( cosm_NET * net );
Description
This is a helper function used by GetWork
and PutWork due to the complexity of
connecting possibly with a firewall. net will be connected to
the server and in a connected state upon return.
Return Values
COSM_PASS on successful connect to the server, or COSM_FAIL on failure.
Errors
None.
Example
See client.c
Run
Syntax
s32 Run( PACKET_ACTIVE * work, u64 iterations );
Description
Process the work for up to iterations loops.
The algorithms used will depend entirely on the project. Before
returning (without error) from this function the work
must be in a checkpointable state.
Return Values
STATE_INVALID on error, STATE_DONE if the work was
finished, or STATE_ALIVE if there is more work to be done.
Errors
None.
Example
See client.c
Speed
Syntax
u64 Speed( void );
Description
Benchmark the client speed. This will be used both for checkpointing
and to request a days worth of work.
Return Values
Number of iterations per second (or the timespan set) that the
client can handle, or a default speed on error.
Errors
None.
Example
See client.c
Test
Syntax
s32 Test( void );
Description
Run selftests for the client, including CosmTest().
Return Values
COSM_PASS on success, or a negative number corresponding to the test
that failed.
Errors
None.
Example
See client.c
Config
Syntax
s32 Config( void );
Description
Asks the user for all needed configuration information. This will be
logging level, network settings, and other project specific data.
Return Values
COSM_PASS on success, or COSM_FAIL on failure.
Errors
None.
Example
See client.c
© Mithral Communications & Design Inc. 1995-2000.
All rights reserved.
Mithral® and Cosm® are trademarks of
Mithral Communications & Design, Inc.
Document last modified: Jan 15, 2013
|