From commits-return-7244-apmail-commons-commits-archive=commons.apache.org@commons.apache.org Fri Jul 03 06:36:07 2009 Return-Path: Delivered-To: apmail-commons-commits-archive@minotaur.apache.org Received: (qmail 49921 invoked from network); 3 Jul 2009 06:36:07 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 3 Jul 2009 06:36:07 -0000 Received: (qmail 49293 invoked by uid 500); 3 Jul 2009 06:36:17 -0000 Delivered-To: apmail-commons-commits-archive@commons.apache.org Received: (qmail 49197 invoked by uid 500); 3 Jul 2009 06:36:16 -0000 Mailing-List: contact commits-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@commons.apache.org Delivered-To: mailing list commits@commons.apache.org Received: (qmail 49187 invoked by uid 99); 3 Jul 2009 06:36:16 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 03 Jul 2009 06:36:16 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 03 Jul 2009 06:36:14 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id AD80623888CF; Fri, 3 Jul 2009 06:35:54 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r790803 - /commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java Date: Fri, 03 Jul 2009 06:35:54 -0000 To: commits@commons.apache.org From: mturk@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090703063554.AD80623888CF@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: mturk Date: Fri Jul 3 06:35:54 2009 New Revision: 790803 URL: http://svn.apache.org/viewvc?rev=790803&view=rev Log: Readd Pointer as interface Added: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java (with props) Added: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java?rev=790803&view=auto ============================================================================== --- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java (added) +++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java Fri Jul 3 06:35:54 2009 @@ -0,0 +1,174 @@ +/* Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.runtime; + +/** Represents the Operating System C/C++ pointer. + *

+ * Warning:
Using this class improperly may crash the running JVM. + *

+ * @since Runtime 1.0 + */ +public interface Pointer extends Comparable +{ + + /** + * Represents a C/C++ NULL {@code pointer}. + */ + public static final Pointer NULL = NativePointer.NULL; + + /** + * Address of the internal pointer. + *

+ * Depending on the operating system the {@code Number} can be + * either {@code Integer} for 32 bit systems of {@code Long} for + * a 64 bit system. + *

+ * + * @return Internal pointer address casted to the {@code Number}. + */ + public Number address(); + + /** + * Size of the memory area this pointer consumes. + *

+ * If the {@code this} Pointer does not have a length + * the returned size if Pointer {@code SIZEOF}. + *

+ * + * @return Internal pointer size. + */ + public long sizeof(); + + /** + * Check if the pointer is valid + * @return true if the internal pointer is not {@code NULL}. + */ + public boolean IsNull(); + + /** + * Compares this {@code Pointer} to the specified object. + * + * @param other a {@code Pointer} + * @return true if the class of this {@code Pointer} object and the + * class of {@code other} are exactly equal, and the C/C++ + * pointers being pointed to by these objects are also + * equal. Returns false otherwise. + */ + @Override + public boolean equals(Object other); + + + /** + * Free the allocated resource by the Operating system. + *

+ * Note that {@code Object.finalize()} method will call + * this function. However if the native code can block for + * long time explicit {@code free()} should be called. + *

+ * @see NativePointer#finalize() + * @throws Throwable the {@code Exception} raised by this method. + */ + public void free() + throws Throwable; + + /** + * Get a {@code byte} value this {@code pointer} contains at the + * {@code index}. + * + * @return a {@code byte} at {@code index}. + * @throws IndexOutOfBoundsException if {@code index} would cause access + * outside the pointer address space. + * @throws NullPointerException if pointer is {@code null}. + */ + public int peek(int index) + throws IndexOutOfBoundsException, NullPointerException; + + /** + * Set a {@code byte} value to this {@code pointer} at the + * {@code index} location. + * + * @param value Value to set at {@code index}. + * @throws IndexOutOfBoundsException if {@code index} would cause access + * outside the pointer address space. + * @throws NullPointerException if pointer is {@code null}. + */ + public void poke(int index, int value) + throws IndexOutOfBoundsException, NullPointerException; + + /** + * Copy the memory area from {@code this} pointer to {@code dst}. + *

+ * Method uses the {@code memcpy} function to do a copying, meaning + * that {@code source} and {@code destination} memory areas should + * not overlap. + *

+ * + * @param srcPos starting position in the source memory. + * @param dst destination {@code Pointer}. + * @param dstPos starting position in the destination memory. + * @param length the number of bytes to be copied. + * + * @throws IllegalArgumentException if the {@code srcPos} or + * {@code dstPos} is {@code negative} or {@code length} + * is {@code zero}. + * @throws IndexOutOfBoundsException if the operation would cause + * access of data outside allocated memory bounds. + * @throws NullPointerException if {@code this} or {@code dst} is + * {@code null}. + */ + public void copy(long srcPos, Pointer dst, + long dstPos, long length) + throws IndexOutOfBoundsException, IllegalArgumentException, + NullPointerException; + + /** + * Copy the memory area from pointer {@code src} to {@code this} pointer. + *

+ * Method uses the {@code memmove} function to do a copying, meaning + * that {@code source} and {@code destination} memory areas can overlap. + *

+ * + * @param src source {@code Pointer}. + * @param srcPos starting position in the source memory. + * @param dstPos starting position in our memory area. + * @param length the number of bytes to be copied. + * + * @throws IllegalArgumentException if the {@code srcPos} or + * {@code dstPos} is {@code negative} or {@code length} + * is {@code zero}. + * @throws IndexOutOfBoundsException if the operation would cause + * access of data outside allocated memory bounds. + * @throws NullPointerException if {@code this} or {@code dst} is + * {@code null}. + */ + public void move(Pointer src, long srcPos, + long dstPos, long length) + throws IndexOutOfBoundsException, IllegalArgumentException, + NullPointerException; + + + /** + * Returns a string representation of the Pointer. + * The returned string is hexadecimal representation of the underlying + * pointer. + * @return a hexadecimal representation of the pointer. + */ + @Override + public String toString(); + +} + Propchange: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java ------------------------------------------------------------------------------ svn:eol-style = native