2
* Pure Data Packet system implementation: Packet Manager Interface
3
* Copyright (c) by Tom Schouten <pdp@zzz.kotnet.org>
5
* This program is free software; you can redistribute it and/or modify
6
* it under the terms of the GNU General Public License as published by
7
* the Free Software Foundation; either version 2 of the License, or
8
* (at your option) any later version.
10
* This program is distributed in the hope that it will be useful,
11
* but WITHOUT ANY WARRANTY; without even the implied warranty of
12
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13
* GNU General Public License for more details.
15
* You should have received a copy of the GNU General Public License
16
* along with this program; if not, write to the Free Software
17
* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
23
This file contains the pdp packet manager interface specification.
25
It is an implementation of the "Object Pool" pattern with lazy instantiation
28
The pool is a growable array. It can only grow larger. Packets are represented
29
by an integer, which is an index in this array.
31
The standard "pure" packets (the ones which use a flat memory buffer) have recovery
32
for resource depletion (main memory). If an out of memory condition is met
33
on allocation of a new package, the garbage collector kicks in and frees unused
34
packets until the out of memory condition is solved. Since an out of memory
35
condition can be fatal for other parts of the program, pdp also supports a
36
memory limit, to ensure some kind of safety margin.
38
The "not so pure" packets should resolve resource conflicts in their own factory method,
39
since the constructor is responsible for allocating external resources. The standard
40
way to do this is to allocate a packet, free it's resources and allocate a new packet
41
until the resource allocation succeeds. Especially for these kinds of packets, the
42
pdp pool supports an explicit reuse method. This returns a valid packet if it can reuse
43
one (based on the high level type description).
45
Packets that don't have memory managing methods defined in the packet class
46
(Standard packets) are treated as a header concatenated with a flat memory buffer, and
47
can be copied and cloned without problems. So, if a packet contains pointers to other
48
data or code, it can't be a pure packet.
50
The interface to the packet manager contains the following managing methods:
52
* pdp_packet_new: create a new packet or reuse a previous one
53
* pdp_packet_mark_unused: release a packet
54
* pdp_packet_copy_ro: register a packet for read only use
55
* pdp_packet_copy_rw: register a packet for read/write use (this creates a copy if necessary)
56
* pdp_packet_clone_rw: create a new packet using a template, but don't copy the data
58
And two methods for raw data access
60
* pdp_packet_header: retreive the header of the packet
61
* pdp_packet_data: retreive the data buffer of the packet (only for static packets)
63
All the methods declared in this header are supposed to be thread safe, so you
64
can call them from the pd and pdp thread.
71
#include "pdp_symbol.h"
72
#include "pdp_types.h"
74
// this is legacy stuff: images are basic types
75
#include "pdp_image.h"
76
#include "pdp_bitmap.h"
79
#define PDP_HEADER_SIZE 256
83
/* all symbols are C-style */
91
typedef int (*t_pdp_factory_method)(t_pdp_symbol *); //returns bool success
93
/* packet class header */
94
typedef struct _pdp_class
96
/* packet manips: non-pure data packets (using external resources) must define these */
97
t_pdp_packet_method1 wakeup; /* called before returning a reused packet (rc:0->1) */
98
t_pdp_packet_method2 copy; /* copy data from source packet to destination packet */
99
t_pdp_packet_method1 cleanup; /* free packet's resources (destructor) */
100
t_pdp_packet_method1 sleep; /* mark_unused notify: called when refcount reaches zero */
101
t_pdp_symbol *type; /* type template for packet class */
102
t_pdp_factory_method create; /* the constructor: create a packet with uninitialized data */
107
implement garbage collection for fobs.
108
(fobs are forth object dictionaries, but for the gc these count as lists)
111
#define PDP_GC_COLOUR_GREY 0 /* 0 == default: object is reachable */
112
#define PDP_GC_COLOUR_WHITE 1
113
#define PDP_GC_COLOUR_BLACK 2
116
/* packet object header */
120
unsigned int type; /* main datatype of this object */
121
t_pdp_symbol *desc; /* high level type description (sort of a mime type) */
122
unsigned int size; /* datasize including header */
123
unsigned int flags; /* packet flags */
125
/* reference count */
126
unsigned int users; /* nb users of this object, readonly if > 1 */
129
t_pdp_class *theclass; /* if zero, the packet is a pure packet (just data, no member functions) */
131
u32 pad[10]; /* LATER: reserve bytes to provide compatibility with future extensions */
133
union /* each packet type has a unique subheader */
135
t_raw raw; /* raw subheader (for extensions unkown to pdp core system) */
136
struct _image image; /* (nonstandard internal) 16 bit signed planar bitmap image format */
137
struct _bitmap bitmap; /* (standard) bitmap image (fourcc coded) */
138
//t_ca ca; /* cellular automaton state data */
139
//t_ascii ascii; /* ascii packet */
145
/* pdp data packet type id */
146
#define PDP_IMAGE 1 /* 16bit signed planar scanline encoded image packet */
147
//RESERVED: #define PDP_CA 2 /* 1bit toroidial shifted scanline encoded cellular automaton */
148
//RESERVED: #define PDP_ASCII 3 /* ascii packet */
149
//RESERVED: #define PDP_TEXTURE 4 /* opengl texture object */
150
//RESERVED: #define PDP_3DCONTEXT 5 /* opengl render context */
151
#define PDP_BITMAP 6 /* 8bit image packet (fourcc coded??) */
152
//RESERVED: #define PDP_MATRIX 7 /* floating point/double matrix/vector packet (from gsl) */
153
#define PDP_FOB 8 /* small c->forth object wrapper */
156
#define PDP_FLAG_DONOTCOPY (1<<0) /* don't copy the packet on register_rw, instead return an invalid packet */
161
t_pdp_class *pdp_class_new(t_pdp_symbol *type, t_pdp_factory_method create);
164
void pdp_class_addmethod(t_pdp_class *c, t_pdp_symbol *name, t_pdp_attribute_method method,
165
struct _pdp_list *in_spec, struct _pdp_list *out_spec);
168
/* packet factory method + registration */
169
int pdp_factory_newpacket(t_pdp_symbol *type);
172
/* send a message to a packet (packet polymorphy)
173
this returns NULL on failure, or a return list
174
the return list should be freed by the caller */
176
int pdp_packet_op(t_pdp_symbol *operation, struct _pdp_list *stack);
180
void pdp_packet_print_debug(int packet);
183
/* hard coded packet methods */
184
int pdp_packet_copy_ro(int handle); /* get a read only copy */
185
int pdp_packet_copy_rw(int handle); /* get a read/write copy */
186
int pdp_packet_clone_rw(int handle); /* get an empty read/write packet of the same type (only copy header) */
187
void pdp_packet_mark_unused(int handle); /* indicate that you're done with the packet */
188
void pdp_packet_delete(int packet); /* like mark_unused, but really delete when refcount == 0 */
190
t_pdp* pdp_packet_header(int handle); /* get packet header */
191
void* pdp_packet_subheader(int handle); /* get packet subheader */
192
void* pdp_packet_data(int handle); /* get packet raw data */
193
int pdp_packet_data_size(int handle); /* get packet raw data size */
195
int pdp_packet_compat(int packet0, int packet1);
196
int pdp_packet_reuse(t_pdp_symbol *description);
197
int pdp_packet_create(unsigned int datatype, unsigned int datasize); /* create a new packet, don't reuse */
199
int pdp_packet_writable(int packet); /* returns true if packet is writable */
200
void pdp_packet_replace_with_writable(int *packet); /* replaces a packet with a writable copy */
201
//void pdp_packet_mark_unused_atomic(int *handle); /* mark unused + set reference to -1 (for thread synchro) */
205
int pdp_pool_collect_garbage(void); /* free all unused packets */
206
void pdp_pool_set_max_mem_usage(int max); /* set max mem usage */
added
removed
include/pdp_packet.h
