PDL::APIP - Online sa Cloud

PROGRAMA:

NAME

PDL::API - paggawa ng piddles mula sa Perl at C/XS code

DESCRIPTION

Isang simpleng cookbook kung paano gumawa ng piddles nang manu-mano. Sinasaklaw nito ang parehong Perl at ang C/XS
antas. Bukod pa rito, inilalarawan nito ang mga pangunahing gawain ng PDL na maaaring ma-access mula sa iba
mga module. Ang mga gawaing ito ay karaniwang tumutukoy sa PDL API. Kung kailangan mong i-access ang piddles mula sa
C/XS malamang na kailangan mong malaman ang tungkol sa mga function na ito.

SINOPSIS

gumamit ng PDL;
sub mkmypiddle {
...
}

Paglikha a piddle mano-mano mula Perl

Minsan gusto mong gumawa ng piddle mano-mano mula sa binary data. Magagawa mo iyon sa
Antas ng Perl. Kasama sa mga halimbawa sa pamamahagi ang ilan sa mga gawain ng IO. Ang code
Ang snippet sa ibaba ay naglalarawan ng mga kinakailangang hakbang.

gumamit ng Carp;
sub mkmypiddle {
aking $class = shift;
aking $pdl = $class->new;
$pdl->set_datatype($PDL_B);
aking @dims = (1,3,4);
ang aking $size = 1;
para sa (@dims) { $size *= $_ }
$pdl->setdims([@dims]);
aking $dref = $pdl->get_dataref();

# basahin ang data nang direkta mula sa file
buksan ang aking $file, '
my $len = $size*PDL::Core::howbig($pdl->get_datatype);
croak "hindi makapagbasa ng sapat na data" kung
basahin( $file, $$dref, $len) != $len;
isara ang $file;
$pdl->upd_data();

ibalik ang $pdl;
}

Paglikha a piddle in C

Ang sumusunod na halimbawa ay lumilikha ng piddle sa antas ng C. Ginagamit namin ang "Inline" na module na
ay talagang ang paraan sa interface ng Perl at C sa mga araw na ito. Tandaan ang paggamit ng "PDL_INCLUDE",
"PDL_TYPEMAP", "PDL_AUTO_INCLUDE" at "PDL_BOOT" function na na-import mula sa
"PDL::Core::Dev". Ginagamit ang mga ito kasabay ng isang Inline Config na tawag upang matiyak iyon
ang PDL typemap, ang PDL ay may kasamang mga file at ang PDL Core na gawain ay matatagpuan sa panahon
compilation at mamaya runtime execution.

gumamit ng PDL::LiteF;
gumamit ng PDL::Core::Dev;

$a = myfloatseq(); # gamitin ang aming C piddle constructor

print $a->impormasyon,"\n";

# ang dahilan ng config call na ito ay ipinaliwanag sa ibaba
gamitin ang Inline C => Config =>
INC => &PDL_INCLUDE, # tiyaking mahahanap namin ang pdlcore.h atbp
TYPEMAPS => &PDL_TYPEMAP, # gamitin ang PDL typemap
AUTO_INCLUDE => &PDL_AUTO_INCLUDE, # pandaigdigang deklarasyon at kasama
BOOT => &PDL_BOOT; # boot code upang i-load ang Core struct

gumamit ng Inline C;
Inline->init; # kapaki-pakinabang kung gusto mong 'gawin'-load ang script na ito

__DATA__

__C__

static pdl* new_pdl(int datatype, PDL_Indx dims[], int ndims)
{
pdl *p = PDL->pdlnew();
PDL->setdims (p, dims, ndims); /* itakda ang dims */
p->datatype = datatype; /* at uri ng data */
PDL->alocdata (p); /* ilaan ang data chunk */

ibalik p;
}

pdl* myfloatseq()
{
PDL_Indx dims[] = {5,5,5};
pdl *p = new_pdl(PDL_F,dims,3);
PDL_Float *dataf = (PDL_Float *) p->data;
PDL_Indx i; /* ang mga sukat ay maaaring 64bits */

para sa (i=0;i<5*5*5;i++)
dataf[i] = i; /* ang data ay dapat masimulan! */
ibalik p;
}

Pambalot iyong sarili data sa a piddle
Minsan nakakakuha ka ng isang tipak ng data mula sa ibang pinagmulan, halimbawa isang pagpoproseso ng imahe
library, atbp. Ang gusto mo lang gawin sa kasong iyon ay balutin ang iyong data sa isang piddle struct sa
ang antas ng C. Ang mga halimbawa na gumagamit ng diskarteng ito ay matatagpuan sa mga module ng IO (kung saan ang FastRaw
at ginagamit ito ng FlexRaw para sa mmapped na pag-access) at ang module ng Gimp Perl (na ginagamit ito upang i-wrap ang Gimp
mga rehiyon ng pixel sa mga piddle). Ang sumusunod na script ay nagpapakita ng isang simpleng halimbawa:

gumamit ng PDL::LiteF;
gumamit ng PDL::Core::Dev;
gumamit ng PDL::Graphics::PGPLOT;

$b = mkpiddle();

print $b->impormasyon,"\n";

larawan1 $b;

gamitin ang Inline C => Config =>
INC => &PDL_INCLUDE,
TYPEMAPS => &PDL_TYPEMAP,
AUTO_INCLUDE => &PDL_AUTO_INCLUDE,
BOOT => &PDL_BOOT;

gumamit ng Inline C;
Inline->init;

__DATA__

__C__

/* I-wrap ang isang user na ibinigay na tipak ng data sa isang piddle
* Dapat mong tukuyin ang mga sukat (dims,ndims) at
* ang datatype (constant para sa mga datatype ay idineklara
* sa pdl.h; hal PDL_B para sa uri ng byte, atbp)
*
* kapag ang ginawang piddle 'npdl' ay nasira sa
* Perl side ang function na ipinasa bilang 'delete_magic'
* Ang parameter ay tatawagin gamit ang pointer sa pdl structure
* at ang argumentong 'delparam'.
* Nagbibigay ito sa iyo ng pagkakataong magsagawa ng anumang paglilinis
* kailangan yan. Halimbawa, maaaring kailanganin mo
* Tahasang tumawag ng isang function upang palayain ang mga mapagkukunan
* nauugnay sa iyong data pointer.
* Sa pinakakaunting 'delete_magic' ay dapat na i-zero ang data pointer ng piddle:
*
* void delete_mydata(pdl* pdl, int param)
* {
* pdl->data = 0;
*}
* pdl *p = pdl_wrap(mydata, PDL_B, dims, ndims, delete_mydata,0);
*
* Ibinabalik ng pdl_wrap ang pointer sa pdl
* na nilikha.
*/
typedef void (*DelMagic)(pdl *, int param);
static void default_magic(pdl *p, int pa) { p->data = 0; }
static pdl* pdl_wrap(void *data, int datatype, PDL_Indx dims[],
int ndims, DelMagic delete_magic, int delparam)
{
pdl* npdl = PDL->pdlnew(); /* kunin ang walang laman na lalagyan */

PDL->setdims(npdl,dims,ndims); /* itakda ang dims */
npdl->datatype = datatype; /* at uri ng data */
npdl->data = data; /* ituro ito sa iyong data */
/* siguraduhin na ang core ay hindi nakikialam sa iyong data */
npdl->estado |= PDL_DONTTOUCHDATA | PDL_ALLOCATED;
kung (delete_magic != NULL)
PDL->add_deletedata_magic(npdl, delete_magic, delparam);
iba
PDL->add_deletedata_magic(npdl, default_magic, 0);
ibalik ang npdl;
}

#define SZ 256
/* isang talagang hangal na function na gumagawa ng ramp na imahe
* sa katotohanan ito ay maaaring isang opaque function
* sa ilang library na iyong ginagamit
*/
static na PDL_Byte* mkramp(walang bisa)
{
PDL_Byte *data;
int i; /* dapat gumamit ng PDL_Indx para suportahan ang 64bit pdl indexing */

kung ((data = malloc(SZ*SZ*sizeof(PDL_Byte)))) == NULL)
croak("mkramp: Hindi makapaglaan ng memorya");
para sa (i=0;i
data[i] = i % SZ;

ibalik ang data;
}

/* inaalagaan ng function na ito ang kinakailangang paglilinis */
static void delete_myramp(pdl* p, int param)
{
kung (p->data)
libre(p->data);
p->data = 0;
}

pdl* mkpiddle()
{
PDL_Indx dims[] = {SZ,SZ};
pdl *p;

p = pdl_wrap((void *) mkramp(), PDL_B, dims, 2,
delete_myramp,0); /* ang delparam ay kusang nakatakda sa 0 */
ibalik p;
}

Ang bundok mga detalye

Ang Ubod istruktura -- pagkuha at PDL ubod gawain at runtime
Gumagamit ang PDL ng isang pamamaraan na katulad ng ginagamit ng mga Tk module upang hayaang magamit ng ibang mga module
mga pangunahing gawain nito. Ang isang pointer sa lahat ng nakabahaging pangunahing gawain ng PDL ay nakaimbak sa $PDL::SHARE
variable. Dapat makuha ng XS code ang pointer na ito sa oras ng boot upang ang iba pang bahagi ng
Maaaring gamitin ng C/XS code ang pointer na iyon para sa pag-access sa oras ng pagtakbo. Ang paunang paglo-load na ito ng
pinakamadaling makuha ang pointer gamit ang mga function na "PDL_AUTO_INCLUDE" at "PDL_BOOT" na
ay tinukoy at na-export ng "PDL::Core::Dev". Ang karaniwang paggamit sa Inline na module ay mayroon
naipakita na:

gamitin ang Inline C => Config =>
INC => &PDL_INCLUDE,
TYPEMAPS => &PDL_TYPEMAP,
AUTO_INCLUDE => &PDL_AUTO_INCLUDE, # deklarasyon
BOOT => &PDL_BOOT; # code para sa XS boot section

Tinitiyak iyon ng code na ibinalik ng "PDL_AUTO_INCLUDE." pdlcore.h ay kasama at ipinapahayag
ang mga static na variable upang i-hold ang pointer sa "Core" struct. May kamukha ito
ito:

i-print ang PDL_AUTO_INCLUDE;

#isama
static Core* PDL; /* Ang istraktura ay nagtataglay ng mga pangunahing C function */
static na SV* CoreSV; /* Nakakuha ng pointer sa Perl var na may hawak na core structure */

Kinukuha ng code na ibinalik ng "PDL_BOOT" ang variable na $PDL::SHARE at sinisimulan ang
pointer sa "Core" struct. Para sa mga nakakaalam ng kanilang paraan sa paligid ng Perl API narito ang
code:

i-print ang PDL_BOOT;

perl_require_pv ("PDL::Core"); /* siguraduhing na-load ang PDL::Core */
CoreSV = perl_get_sv("PDL::SHARE",FALSE); /* SV* value */
#ifndef aTHX_
#define aTHX_
#endif
kung (CoreSV==NULL)
Perl_croak(aTHX_ "Kinakailangan namin ang PDL::Core module, na hindi natagpuan");
PDL = INT2PTR(Core*,SvIV(CoreSV )); /* Core* value */
kung (PDL->Bersyon != PDL_CORE_VERSION)
Perl_croak(aTHX_ "Ang code ay kailangang muling i-compile laban sa bagong naka-install na PDL");

Ang "Core" struct ay naglalaman ng impormasyon ng bersyon upang matiyak na ang istraktura ay tinukoy sa pdlcore.h
talagang tumutugma sa nakuha sa runtime. Ang code sa itaas ay sumusubok para dito

kung (PDL->Bersyon != PDL_CORE_VERSION)
....

Para sa karagdagang impormasyon sa Core struct tingnan ang PDL::Internals.

Sa mga paghahandang ito, maa-access na ngayon ng iyong code ang mga pangunahing gawain tulad ng ipinakita na sa
ilan sa mga halimbawa sa itaas, hal

pdl *p = PDL->pdlnew();

Bilang default ang C variable na pinangalanang "PDL" ay ginagamit upang i-hold ang pointer sa "Core" struct. Kung
iyon ay (sa alinmang dahilan) isang problema na maaari mong tahasang tukuyin ang isang pangalan para sa
variable na may "PDL_AUTO_INCLUDE" at ang "PDL_BOOT" na mga gawain:

gamitin ang Inline C => Config =>
INC => &PDL_INCLUDE,
TYPEMAPS => &PDL_TYPEMAP,
AUTO_INCLUDE => &PDL_AUTO_INCLUDE 'PDL_Corep',
BOOT => &PDL_BOOT 'PDL_Corep';

Tiyaking ginagamit mo ang parehong identifier na may "PDL_AUTO_INCLUDE" at "PDL_BOOT" at gamitin iyon
parehong identifier sa sarili mong code. Hal, pagpapatuloy mula sa halimbawa sa itaas:

pdl *p = PDL_Corep->pdlnew();

ilan pinili ubod gawain ipinaliwanag
Ang buong kahulugan ng "Core" struct ay matatagpuan sa file pdlcore.h. Sa
ang pagsunod sa pinakamadalas na ginagamit na mga function ng miyembro ng istrukturang ito ay maikli na ipinaliwanag.

· "pdl *SvPDLV(SV *sv)"

· "pdl *SetSV_PDL(SV *sv, pdl *it)"

· "pdl *pdlnew()"

Ang "pdlnew" ay nagbabalik ng isang walang laman na bagay na pdl na nangangailangan ng karagdagang pagsisimula upang mabuksan ito
sa tamang piddle. Halimbawa:

pdl *p = PDL->pdlnew();
PDL->setdims(p,dims,ndims);
p->datatype = PDL_B;

· "pdl *null()"

· "SV *kopya(pdl* p, char* )"

· "walang bisa *smalloc(STRLEN nbytes)"

· "int howbig(int pdl_datatype)"

· "void add_deletedata_magic(pdl *p, void (*func)(pdl*, int), int param)"

· "walang bisa allocdata(pdl *p)"

· "walang bisa make_physical(pdl *p)"

· "walang bisa make_physdims(pdl *p)"

· "walang bisa make_physvaffine(pdl *p)"

· "void qsort_X(PDL_Xtype *data, PDL_Indx a, PDL_Indx b)" at "void
qsort_ind_X(PDL_Xtype *data, PDL_Indx *ix, PDL_Indx a, PDL_Indx b)"

kung saan ang X ay isa sa B,S,U,L,F,D at Xtype ay isa sa Byte, Short, Ushort, Long, Float o
Doble. Ang PDL_Indx ay ang uri ng C integer na naaayon sa naaangkop na laki ng pag-index
para sa pagsasaayos ng perl (ivsize at ivtype). Maaari itong maging 'mahaba' o 'mahaba
long' depende sa kung ang iyong perl ay 32bit o 64bit na pinagana.

· "float NaN_float" at "double NaN_double"

Ito ay mga pare-pareho upang makabuo ng mga kinakailangang halaga ng NaN.

· "void pdl_barf(const char* pat,...)" at "void pdl_warn(const char* pat,...)"

Ito ay mga katumbas ng C-code ng "barf" at "warning". Kasama sa mga ito ang espesyal na paghawak ng
error o mga mensahe ng babala sa panahon ng pthreading (ie processor multi-threading) na
ipagpaliban ang mga mensahe hanggang matapos ang pthreading. Kapag tapos na ang pthreading,
Tinatawag ang "barf" o "warning" ni perl kasama ng mga napagpaliban na mensahe. Ito ay kinakailangan upang mapanatili
mula sa pagtawag sa "barf" o "babala" ni perl sa panahon ng pthreading, na maaaring magdulot ng mga segfault.

Tandaan na ang "barf" at "warn" ay muling tinukoy (gamit ang c-preprocessor macros) sa
pdlcore.h sa "PDL->barf" at "PDL->warn". Ito ay upang panatilihin ang anumang XS o PP code mula sa
direktang pagtawag sa "barf" o "babala" ni perl, na maaaring magdulot ng mga segfault habang
pthreading.

Tingnan ang PDL::ParallelCPU para sa higit pang impormasyon sa pthreading.

Gamitin ang PDL::APIP online gamit ang mga serbisyo ng onworks.net